From 9d59af5ab4c55fd24390f1aea2c4cb9c7103bc1d Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 06:13:57 +0000 Subject: [PATCH 1/5] docs: make AGENTS.md the home of design principles Move the decoupling principle, extension contracts, pre-release policy and documentation rules from CONTRIBUTING.md into AGENTS.md as protocol-first design rules: one protocol per boundary, complexity kept in adapters, one home per setting and datum, no compatibility layers, and documentation rules. CONTRIBUTING.md keeps workflow, review, checks and naming. The architecture overview keeps its boundary responsibilities and links to AGENTS.md for each protocol's code and document. --- AGENTS.md | 161 +++++++++++++++++++++++++++++++++++++++---- CONTRIBUTING.md | 143 +++++--------------------------------- docs/architecture.md | 40 +++++------ 3 files changed, 185 insertions(+), 159 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 25c344b6f..7b4437e06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,16 +1,153 @@ # OpenAgentCore development -Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing code. It owns repository -boundaries, architecture, workflow, required checks and independent blind review. -Use [docs/development.md](docs/development.md) for checkout and component guidance. - -- Keep Core, Runtime, Harness and Sandbox Provider ownership separate through the - shared protocols; see [decoupling](CONTRIBUTING.md#decoupling-principle). -- To add a Harness or Sandbox Provider, start at - [Choose an extension boundary](docs/development.md#choose-an-extension-boundary). -- Identify every API route's caller and credential in [the API index](docs/api/README.md). +This file holds the design rules every change follows. [CONTRIBUTING.md](CONTRIBUTING.md) +holds workflow, review, checks and naming; [docs/development.md](docs/development.md) +holds setup and the repository map. + +## Design principles + +OpenAgentCore is protocol-first and modular. Core orchestrates operations that +protocols define. Sandbox Providers, Runtimes, Harnesses and model providers are +replaceable implementations of those protocols; user-owned machines, E2B, Docker +and microsandbox expose the same execution protocol. + +Existing code that breaks a rule below is a gap, not a precedent. Do not copy or +extend it. + +### Protocols at every boundary + +- Each boundary between components has exactly one protocol: one code file + (interface, wire types and validators) and one document. Change the code and the + document together, and update every implementation in the same change. +- Protocols are deterministic. Declare each operation explicitly and type each + outcome. Declare support; never discover it through optional-interface type + assertions, name checks or implicit fallbacks. An unsupported operation returns + an explicit typed error. +- A component joins the system only by implementing a protocol. It gets no private + entry point, side channel or path selected by its name. + +| Boundary | Protocol code | Protocol doc | +| --- | --- | --- | +| Application–Core (`/v1`) | `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) | +| Web and operators–Core (`/core/v1`) | `contracts/agents-api/core.openapi.yaml` | [Web management API](docs/api/web-management.md) | +| Nodes and daemons–Core (`/api/v1`) | `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](docs/api/README.md#machine-connection-api) | +| Core–Sandbox Provider | `services/agents-api/internal/sandbox/sandbox_provider.go`, `services/agents-api/internal/sandbox/operations.go`, `services/agents-api/internal/providercontract/operations.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | +| Core–sandbox node | `services/agents-api/internal/sandbox/node/wire.go`, `services/agents-api/internal/sandbox/node/generation_wire.go` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | +| Provider–Runtime startup | `internal/runtimebootstrap/bootstrap.go` | [Runtime bootstrap](docs/runtime-bootstrap.md) | +| Core–Runtime wire | `internal/agentdaemon/proto/*.go` | [Core–Runtime protocol](docs/runtime-protocol.md) | +| Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go`, `internal/harnessconfig/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | +| Harness–Model provider | `internal/modelprovider/config.go` | [Model execution](contracts/agents-api/model-execution.md) | + +A boundary listed with more than one code file does not meet this rule yet; do not +add files to it. + +### Complexity stays in the adapter + +New complexity lives in the adapter that needs it and never spreads outward. + +| Component | Adapter | +| --- | --- | +| Sandbox Provider | `services/agents-api/internal/sandbox//` and its entry in `services/agents-api/internal/sandbox/providers/registry.go`; when present, its helper in `services/agents-api/tools/-provider/` and its operator material in `services/agents-api/deploy//` | +| Harness | `apps/parsar-daemon/internal/agent//`, its native configuration in `internal/harnessconfig//`, its entry in `internal/harnessconfig/builtin/catalog.json` and its Runtime image in `services/agents-api/deploy//` | +| Model provider | The Harness adapters that declare its model protocol; a new model protocol is a change to `internal/modelprovider` | + +- A new Sandbox Provider, Harness, model provider or vendor feature changes only its + adapter. It adds no Core execution path, store table or column, migration, + deployment or configuration field, API field or Web UI specific to that vendor or + Harness. +- When the protocol cannot express what an adapter needs, change the protocol as a + change of its own: edit its code and document, update every implementation, and + have it reviewed on its own. Never add an optional side interface for one + implementation. +- Example: making one sandbox vendor pause idle compute is that vendor's Provider's + job, done behind the existing lifecycle operations. A vendor-specific pause + interface, a new Core resume path, pause receipts in the store and a vendor idle + setting in the deployment go beyond an adapter change. + +Each component owns one part of execution: + +| Component | Owns | +| --- | --- | +| Core | Durable Session and Turn state, admission and scheduling | +| Sandbox Provider | Compute selection, creation, bootstrap, renewal and reclamation | +| Runtime | Preparation inside the Environment (files, tool configuration, packages, capabilities) and execution | +| Harness adapter | Translation of the common execution contract into native operations | + +- Executor and compute lifetimes are separate; see + [Executor and Turn lifetimes](docs/runtime-protocol.md#executor-and-turn-lifetimes). + Capability preparation follows [Environments](contracts/agents-api/environments.md#runtime-capability-preparation), + and isolation belongs to the outer Environment; see + [Runtime and outer isolation](docs/design-principles.md#runtime-and-outer-isolation). +- Fix shared lifecycle, admission, cancellation, reuse and performance problems in + the common flow, never in branches selected by a Harness, Runtime or vendor name. +- Express compatibility through declared capabilities and validate each selected + combination explicitly. Reject an unsupported combination with an explicit error. + Never substitute another implementation or give a capability a different meaning + per vendor. +- Core preparation and execution never branch on operating system or Environment + source. Platform support requires native CI builds and automated tests; + cross-compilation alone is insufficient. +- Each rule has one authored definition. Generate cross-language projections from + it or check them against shared fixtures. + +### One home for each setting and datum + +- Write each setting and each piece of data in one place and read it from that + place. Keep no second copy, no environment-variable or file fallback and no alias. +- Keep configuration files together. Where that is impossible, group them by + category. Never scatter them. +- A new setting joins one of the categories below and lives beside its peers. + [Configuration](docs/configuration.md) documents the settings themselves. + +| Category | Home | Written by | +| --- | --- | --- | +| Process settings | `/config.json`; the installer defaults `` to `~/.oac/core` | The operator, applied with `oac apply` | +| Derived process files | `/generated/` | `oac apply` only | +| Secrets | `/secrets/`, one file per secret | The installer and `oac` commands | +| Installation identity and local provider receipts | `/state.json` and `/state/` | The installer tools and Core's provider helpers | +| Runtime settings | Core's PostgreSQL | Web or `/core/v1` | +| Execution data | Core's PostgreSQL | Core, through its APIs | +| Node configuration and identity | `~/.oac/nodes//` in the node account's home | The node installer and node | +| Self-hosted executor | `~/.oac/environments//` | The native installer and daemon | +| Runtime daemon state | `~/.oac/daemon//`; `OAC_RUNTIME_HOME` replaces `~/.oac` | The daemon | +| Build output | `~/.oac/build/`; `OAC_DEV_HOME` replaces `~/.oac` | `make` targets | +| Test artifacts | Under `~/.oac/` | Tests and acceptance runs | + +### Pre-release: no compatibility layers + +OpenAgentCore is pre-release. Replace superseded interfaces, execution paths, files +and documents outright. Keep no version fallback, compatibility shim, alias or +migration for retired behavior unless an explicit upgrade contract requires it. +Keep the pinned official public protocol, valid data and still-used, verified +infrastructure; do not rewrite working infrastructure only to rename it. + +## Documentation + +- One fact, one place. Link to the owning document instead of restating it. The + owner map is [Documentation ownership](CONTRIBUTING.md#documentation-ownership). +- Keep a subject together in one document or section. +- Give each document one audience and one job. Order it for reading: what the + subject is, how to do the task, then reference detail. +- Write plainly and helpfully. State what the system does and what the reader does. + Leave out filler, hedging, defensive negations, process history (PR or design + numbers, "retired", "former", "this candidate") and task chronology. +- Delete obsolete, historical and duplicate documentation outright. Qualification + evidence stays only while it qualifies current behavior. +- Write documentation and code comments in English. The root README also has a + Chinese version; user-facing product copy may be bilingual. +- Markdown in `docs/`, component guides and `contracts/` is the authored source. + Generated copies, such as the `apps/docs` content and generated references, are + never edited by hand: change the source and regenerate. +- Update the owning document in the same branch as the rule, boundary, workflow or + generated contract it describes. + +## Working in this repository + +- [CONTRIBUTING.md](CONTRIBUTING.md): workflow, independent review, required checks + and naming. +- [docs/development.md](docs/development.md): setup, the repository map and + [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). +- [API index](docs/api/README.md): each route's caller and credential. - Run `make sqlc-generate` after query changes and `make openapi` after handler - changes; review and commit the generated contracts with their source changes. + changes. Review and commit the generated contracts with their source. - Run `make check` before reporting completion. -- Update the canonical documentation in the same branch when changing a rule, - boundary, workflow or generated contract. Keep this file a short index. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 258f02624..26d1f2d3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,33 @@ # Contributing to OpenAgentCore Start with [Develop OpenAgentCore](docs/development.md) for checkout, toolchains, -the repository map and focused checks. This guide owns repository-wide rules only: -documentation ownership, the repository boundary, the decoupling principle, -workflow and review, required checks and naming. +the repository map and focused checks. [AGENTS.md](AGENTS.md) owns the design +principles and documentation rules. This guide owns how to work in the repository: +documentation ownership, the repository boundary, workflow and review, required +checks and naming. -Every other rule has one canonical owner, listed below. Change that owner, not a -copy, when a contract changes. +Every other subject has one canonical owner, listed below. ## Documentation ownership | Subject | Canonical source | | --- | --- | +| Design principles, protocol boundaries, storage layout and documentation rules | [AGENTS.md](AGENTS.md) | | User concepts and authority | [Design principles](docs/design-principles.md) | | Architecture overview and diagrams (a map that links to the owners below) | [Architecture](docs/architecture.md) | | Developer setup, repository map and extension boundaries | [Develop OpenAgentCore](docs/development.md) | | API callers, credentials and route inventory | [API index](docs/api/README.md) | | Public wire types and qualified behavior | [Agents API contracts](contracts/agents-api/README.md), [pinned upstream](contracts/agents-api/upstream.json), and linked operation contracts | | Core service implementation constraints | [Agents API implementation constraints](services/agents-api/IMPLEMENTATION.md) and [service README](services/agents-api/README.md) | -| Provider-to-Runtime startup input | [Runtime bootstrap](docs/runtime-bootstrap.md) and `internal/runtimebootstrap` | -| Runtime messages, Executor/Turn lifetimes, receipts and failure ownership | [Core–Runtime protocol](docs/runtime-protocol.md) and `internal/agentdaemon/proto` | +| Provider-to-Runtime startup input | [Runtime bootstrap](docs/runtime-bootstrap.md) | +| Runtime messages, Executor/Turn lifetimes, receipts and failure ownership | [Core–Runtime protocol](docs/runtime-protocol.md) | | Environment ownership and capability preparation (Skills, Plugins, MCP, `packages.system`) | [Environments](contracts/agents-api/environments.md) | -| Adding a Harness (steps) | [Harness onboarding](contracts/agents-api/harness-onboarding.md), `apps/parsar-daemon/internal/agent/harness.go` and `internal/harnessconfig/harness.go` | +| Adding a Harness (steps) | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | | Built-in Harness identifiers, configuration/profile bindings and display names | `internal/harnessconfig/builtin/catalog.json` and its [generated reference](contracts/agents-api/harness-catalog.md) | | Effective MCP bindings and credential authority | [Environment MCP](contracts/agents-api/environments.md#skills-plugins-and-environment-mcp) and `apps/parsar-daemon/internal/agent/mcp_binding.go` | | Harness qualification and acceptance | [Harness integration](contracts/agents-api/harnesses.md) | | Harness selection and Agent defaults | [Harness selection](contracts/agents-api/harness-selection.md) | -| Adding a Sandbox Provider | [Sandbox Provider guide](docs/sandbox-provider.md) and `services/agents-api/internal/sandbox/sandbox_provider.go` | +| Adding a Sandbox Provider | [Sandbox Provider guide](docs/sandbox-provider.md) | | Provider selection, sandbox deployment and E2B setup | [Sandbox deployment](contracts/agents-api/sandbox-deployment.md) | | Hosted sandbox nodes | [Hosted sandbox manager](services/agents-api/HOSTED-SANDBOX-MANAGER.md) | | Claude private bridge and Runtime artifact | [Claude SDK adapter](packages/claude-sdk-adapter/README.md) | @@ -37,21 +38,6 @@ copy, when a contract changes. | Web components, interaction and visual rules | [Web design](apps/web/DESIGN.md) and [Web architecture](docs/web/architecture.md) | | Documentation website generation | [Docs app](apps/docs/README.md) | -### Documentation rules - -- English Markdown in `docs/`, component guides and `contracts/` is authored - source. The docs app generates guide pages and API references from it. Never - edit generated copies to establish a different rule. -- Keep documentation and code comments in English. The root README is provided - in English and Chinese; user-facing product copy may be bilingual. -- Historical acceptance records keep their original revisions and limits. They - are evidence, not current instructions or authority to restore a retired - implementation. Keep task chronology and rollout reports out of contributor rules. -- Keep current integration guidance separate from historical qualification evidence. -- A guide may summarize a workflow but must link to the owning contract for - versions, accepted values, precedence and lifecycle rules. Do not maintain - another normative copy. Generated references are projections, not new owners. - ## Repository boundary This repository is the standalone execution substrate copied from Parsar at the @@ -109,25 +95,14 @@ databases, credentials and migrations. The product uses Core exclusively; it has coverage in `contracts/agents-api/README.md` until the complete target is verified. Reconcile current coverage summaries with merged routes and recorded acceptance; distinguish accepted profiles, partial implementation, missing operations and - unverified semantics. Retain historical evidence with its original scope. Handler + unverified semantics. Keep each evidence record at its original scope. Handler counts are not compatibility percentages, and an active provider probe is not deployment qualification. -- No legacy Agents API compatibility requirement takes precedence over this - design. Replace an unsuitable implementation instead of growing compatibility - branches. Preserve reusable, verified infrastructure rather than rewriting it - merely for new names or directories. Replacements may retire obsolete private - interfaces and history backfills in bounded PRs; this does not authorize deleting - product data or changing unrelated product behavior. -- Every concrete harness interaction goes through the common Runtime contract - and its adapter. Extend that contract minimally when a current operation cannot - be expressed; never put native capability logic or transport conversion into - Core handlers, storage or scheduling. Qualify public workflows through the same - shared chain; direct native probes establish feasibility only. -- Keep engine-specific types, process management and protocol translation inside - execution adapters. Native workspace execution must use the declared Environment - directory; a separate native history/configuration directory is not a workspace. - The public API and persistence/application core must not - interpret Parsar product payloads or depend on one engine's native item types. +- Qualify public workflows through the common Runtime contract and Harness + adapter; direct native probes establish feasibility only. +- Native workspace execution must use the declared Environment directory; a + separate native history/configuration directory is not a workspace. The public + API and persistence/application core must not interpret Parsar product payloads. Prefer maintained upstream SDKs and native execution protocols over a second hand-written model/tool loop or a general-purpose compatibility framework. - Verify an independent official-client workflow before a Parsar integration. @@ -174,88 +149,6 @@ databases, credentials and migrations. The product uses Core exclusively; it has - Product resources use `/app/` and never become Core API or database conventions. - It is excluded from Core distributions and cannot become a service dependency. -## Decoupling principle - -Core orchestrates protocol-defined operations. Sandbox Providers, Runtime -implementations, Harnesses and model providers are replaceable components. -User-owned machines, E2B, Docker and other Environments expose the same -execution protocol. - -Two lifetimes stay separate: - -| Component | Owns | -| --- | --- | -| Resource management (Sandbox Provider) | Selecting machines and capacity; creating, bootstrapping, renewing and reclaiming Environments | -| Runtime | Initializing files, tool configuration, packages and capabilities; executing work and recovering inside an Environment | - -Closing a Session Executor does not release its allocation, destroy its -Environment or delete its workspace; see -[Executor and Turn lifetimes](docs/runtime-protocol.md#executor-and-turn-lifetimes). -Environment preparation state belongs to the Environment, independently of any -managed allocation. Both user-owned and managed machines use the same frozen -preparation input and initializer; resource managers never run installation steps. -Capability preparation follows [Environments](contracts/agents-api/environments.md#runtime-capability-preparation). -The Runtime is not a sandbox; see -[Runtime and outer isolation](docs/design-principles.md#runtime-and-outer-isolation). - -- Keep component boundaries explicit through shared interfaces and versioned - protocols. Register implementations behind those interfaces. Adding an - implementation must not require a new orchestration path selected by its name. - Sandbox registration, configuration adaptation and persistence boundaries follow - the [Sandbox Provider guide](docs/sandbox-provider.md#register-the-provider-kind). - Resource operation declarations are exhaustive and validated against the existing - small interfaces; support is never inferred from method presence. See the - [explicit operation contract](docs/sandbox-provider.md#explicit-operation-contracts). -- Core owns durable Session/Turn state and scheduling. Runtime owns local - execution resources. Harness adapters translate the common execution contract - into native operations; model and sandbox provider details stay behind their - interfaces. -- Fix shared lifecycle, admission, cancellation, reuse and performance problems - in the common protocol or flow, not with Harness-, Runtime- or vendor-specific - branches in Core. Adapters may differ natively but keep shared semantics. -- Public Harnesses explicitly implement every extension interface, returning the - shared Unsupported error when unqualified; required lifecycle obligations cannot - be skipped. Capability declarations must be complete. Follow the single - [Harness onboarding contract](contracts/agents-api/harness-onboarding.md). -- Express compatibility through declared capabilities and validate selected - combinations explicitly. Public MCP origin and credential authority follow the - [Environment MCP contract](contracts/agents-api/environments.md#public-mcp-connection-origin); - changing an input source must not change outbound network or credential scope. Replaceability does not mean every model, Harness and - Environment combination is supported. Never silently substitute another - implementation or give a capability different meanings per vendor. -- Core preparation and execution never branch on operating system or - Environment source. Platform support requires native CI builds and automated - tests; cross-compilation alone is insufficient. -- Evolve shared contracts and their implementations together, document - ownership and validate the same contract across implementations. Each rule has - one authored definition; cross-language projections are generated from it or - checked against common fixtures. Bootstrap credentials use the Runtime-owned - launch input, never a Provider-authored private auth file. This rule - does not claim every implementation already meets every target, change the - pinned public API, or authorize unrelated refactors. - -### Extension contracts - -| Boundary | Canonical guide | Code entry point | -| --- | --- | --- | -| Provider–Runtime startup | [Runtime bootstrap](docs/runtime-bootstrap.md) | `internal/runtimebootstrap` | -| Core–Runtime wire | [Core–Runtime protocol](docs/runtime-protocol.md) | `internal/agentdaemon/proto` | -| Harness | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | `apps/parsar-daemon/internal/agent/harness.go`, `internal/harnessconfig/harness.go` | -| Sandbox Provider | [Sandbox Provider guide](docs/sandbox-provider.md) | `services/agents-api/internal/sandbox/sandbox_provider.go` | - -Shared wire types and validators live only in `internal/agentdaemon/proto`. -Change both peers together with an exact wire-version check; do not add a -parallel schema or a historical wire fallback. Capability completeness and -interface coverage are mandatory extension gates under the -[explicit declaration contract](docs/runtime-protocol.md#explicit-capability-declarations). - -### Pre-release policy - -OpenAgentCore is pre-release. Replace superseded internal interfaces and -execution paths cleanly; do not retain version fallbacks, compatibility shims, -aliases or migrations without an explicit upgrade contract. Preserve the pinned -official public protocol, valid data and still-used infrastructure. - ## Workflow and review ### Before you start @@ -288,11 +181,8 @@ broader compatibility target is complete from one merged batch. 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/` and build output under - `${OAC_DEV_HOME:-$HOME/.oac}`. Runtime state uses `${OAC_RUNTIME_HOME:-$HOME/.oac}`. - New or changed routes identify their caller and credential in the [API index](docs/api/README.md) and link their detailed contract. -- Update the owning guide when architecture, ownership or generated contracts change. ### Review @@ -376,7 +266,6 @@ probes are not current validation entry points. | Runtime binary | `oac-daemon` | | Filesystem and initialization helpers | `oac-*` | | Runtime settings | `OAC_RUNTIME_*` | -| Runtime state | `~/.oac/daemon` | | Reserved Environment `env` prefix | `OAC_` | | Provider ownership labels | `io.oac.*` | | E2B metadata | `oac_*` | diff --git a/docs/architecture.md b/docs/architecture.md index c01664cfd..7d945be7e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -70,30 +70,30 @@ starting work. Core does not isolate tools, run a model or talk to a vendor SDK directly. It selects implementations through interfaces and never branches on a harness, operating system or provider name. See -[the decoupling principle](../CONTRIBUTING.md#decoupling-principle) and the +[Complexity stays in the adapter](../AGENTS.md#complexity-stays-in-the-adapter) and the [repository map](development.md#repository-map). ## Protocol boundaries -The numbers below match the overview. Each contract defines behavior, ownership, -errors and completion semantics as well as types or method signatures. - -| Boundary | Contract | Responsibility | Canonical guide | -| --- | --- | --- | --- | -| 1. Application / Core | Agents API over HTTP / SSE | Sessions, Turns, inputs, Items, files and events | [Public API](api/public-agent-api.md) | -| 2. Core / Sandbox Provider | `SandboxProvider` interface | Compute creation, observation, renewal, bootstrap and reclamation | [Sandbox Provider guide](sandbox-provider.md) | -| 3. Core / Runtime | Typed Core-Runtime messages | Capability declarations, preparation, execution, cancellation, recovery and receipts | [Core-Runtime protocol](runtime-protocol.md) | -| 4. Runtime / Harness | `ExecutorFactory`, `Executor`, `Turn` and separate optional interfaces | Native configuration, execution, event translation and confirmed cleanup | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) | -| Harness / Model Provider | Model API | Model inference through a protocol supported by the selected Harness | [Model execution](../contracts/agents-api/model-execution.md) | - -The [bootstrap contract](runtime-bootstrap.md) carries the Runtime's startup -input across the provisioning boundary. After connection, capability preparation -belongs to Runtime; the Provider does not become a second execution path. - -Replaceability does not mean every combination works. Supported combinations are -declared as capabilities and validated explicitly; see -[Harness selection](../contracts/agents-api/harness-selection.md) and the -[coverage record](../contracts/agents-api/README.md). +The numbers below match the overview. Each protocol defines behavior, ownership, +errors and completion semantics as well as types or method signatures. Its code +and document are listed in [Protocols at every boundary](../AGENTS.md#protocols-at-every-boundary). + +| Boundary | Responsibility | +| --- | --- | +| 1. Application / Core | Sessions, Turns, inputs, Items, files and events over HTTP / SSE | +| 2. Core / Sandbox Provider | Compute creation, observation, renewal, bootstrap and reclamation | +| 3. Core / Runtime | Capability declarations, preparation, execution, cancellation, recovery and receipts | +| 4. Runtime / Harness | Native configuration, execution, event translation and confirmed cleanup | +| Harness / Model Provider | Model inference through a protocol supported by the selected Harness | + +The Runtime's startup input crosses the provisioning boundary. After connection, +capability preparation belongs to Runtime; the Provider does not become a second +execution path. + +Not every combination of Harness, model and Environment works. The supported ones +are recorded in [Harness selection](../contracts/agents-api/harness-selection.md) +and the [coverage record](../contracts/agents-api/README.md). ## A Session, end to end From ad8e8322fcd83a6d81e4fd816c8ca3e4fac10473 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 06:48:02 +0000 Subject: [PATCH 2/5] docs: tighten AGENTS.md design principles after review Complete the boundary table with every protocol file and the generated OpenAPI sources, list the files each adapter touches, add known gaps, correct component ownership and the storage layout, and add the no hard-wrap documentation rule. Move the remaining adapter rules out of CONTRIBUTING.md, collapse its per-boundary ownership rows into AGENTS.md, drop contradicting evidence wording and the stale AGENTS.md name-guard exception. --- AGENTS.md | 133 +++++++++++++++++++++++------------- CONTRIBUTING.md | 35 ++++------ scripts/name-allowlist.json | 5 -- 3 files changed, 99 insertions(+), 74 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b4437e06..85e1f47be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,7 @@ # OpenAgentCore development -This file holds the design rules every change follows. [CONTRIBUTING.md](CONTRIBUTING.md) -holds workflow, review, checks and naming; [docs/development.md](docs/development.md) -holds setup and the repository map. +This file holds the design rules every change follows. +[Working in this repository](#working-in-this-repository) links to everything else. ## Design principles @@ -11,9 +10,6 @@ protocols define. Sandbox Providers, Runtimes, Harnesses and model providers are replaceable implementations of those protocols; user-owned machines, E2B, Docker and microsandbox expose the same execution protocol. -Existing code that breaks a rule below is a gap, not a precedent. Do not copy or -extend it. - ### Protocols at every boundary - Each boundary between components has exactly one protocol: one code file @@ -28,49 +24,68 @@ extend it. | Boundary | Protocol code | Protocol doc | | --- | --- | --- | -| Application–Core (`/v1`) | `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) | -| Web and operators–Core (`/core/v1`) | `contracts/agents-api/core.openapi.yaml` | [Web management API](docs/api/web-management.md) | -| Nodes and daemons–Core (`/api/v1`) | `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](docs/api/README.md#machine-connection-api) | -| Core–Sandbox Provider | `services/agents-api/internal/sandbox/sandbox_provider.go`, `services/agents-api/internal/sandbox/operations.go`, `services/agents-api/internal/providercontract/operations.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | -| Core–sandbox node | `services/agents-api/internal/sandbox/node/wire.go`, `services/agents-api/internal/sandbox/node/generation_wire.go` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | +| Application–Core (`/v1`) | `contracts/agents-api/openapi.yaml`, generated from `contracts/agents-api/v1/*.go` | [Agents API guide](docs/api/public-agent-api.md) | +| Web and operators–Core (`/core/v1`) | `contracts/agents-api/core.openapi.yaml`, generated from `contracts/agents-api/v1/*.go` | [Web management API](docs/api/web-management.md) | +| Nodes and daemons–Core (`/api/v1`) | `contracts/agents-api/runtime.openapi.yaml`, generated from `contracts/agents-api/v1/*.go` | [Machine connection API](docs/api/README.md#machine-connection-api) | +| Core–Sandbox Provider | `sandbox_provider.go`, `suspension.go`, `selection.go` and `operations.go` in `services/agents-api/internal/sandbox/`; `services/agents-api/internal/providercontract/operations.go`; `services/agents-api/internal/runtimeobs/source.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | +| Core–sandbox node | `wire.go`, `generation_wire.go`, `generation_json.go` and `operations.go` in `services/agents-api/internal/sandbox/node/` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | | Provider–Runtime startup | `internal/runtimebootstrap/bootstrap.go` | [Runtime bootstrap](docs/runtime-bootstrap.md) | | Core–Runtime wire | `internal/agentdaemon/proto/*.go` | [Core–Runtime protocol](docs/runtime-protocol.md) | -| Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go`, `internal/harnessconfig/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | -| Harness–Model provider | `internal/modelprovider/config.go` | [Model execution](contracts/agents-api/model-execution.md) | +| Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go`, with result types and errors in `apps/parsar-daemon/internal/agent/*.go`; `internal/harnessconfig/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | +| Harness–Model provider | `internal/modelprovider/config.go`, `internal/harnessconfig/provider.go` | [Model execution](contracts/agents-api/model-execution.md) | -A boundary listed with more than one code file does not meet this rule yet; do not -add files to it. +`make openapi` generates the three OpenAPI files from the Go types and the handler +annotations in `services/agents-api/`; never edit them by hand. Rows that list more +than one file, a glob or a directory do not meet the single-file rule yet; do not +add files to them. ### Complexity stays in the adapter -New complexity lives in the adapter that needs it and never spreads outward. - -| Component | Adapter | -| --- | --- | -| Sandbox Provider | `services/agents-api/internal/sandbox//` and its entry in `services/agents-api/internal/sandbox/providers/registry.go`; when present, its helper in `services/agents-api/tools/-provider/` and its operator material in `services/agents-api/deploy//` | -| Harness | `apps/parsar-daemon/internal/agent//`, its native configuration in `internal/harnessconfig//`, its entry in `internal/harnessconfig/builtin/catalog.json` and its Runtime image in `services/agents-api/deploy//` | -| Model provider | The Harness adapters that declare its model protocol; a new model protocol is a change to `internal/modelprovider` | - -- A new Sandbox Provider, Harness, model provider or vendor feature changes only its - adapter. It adds no Core execution path, store table or column, migration, - deployment or configuration field, API field or Web UI specific to that vendor or - Harness. +New complexity lives in the adapter that needs it and never spreads outward. A new +implementation adds or changes only these files. Directory names differ per +Harness: Claude uses `claude_sdk`, `claudesdk` and `claude`. + +- **Sandbox Provider:** its package `services/agents-api/internal/sandbox//`, + its construction in `services/agents-api/internal/sandbox/providers/.go` + and its entry in `services/agents-api/internal/sandbox/providers/registry.go`; + when present, its helper in `services/agents-api/tools/-provider/` and its + operator material in `services/agents-api/deploy//`. +- **Harness:** its adapter in `apps/parsar-daemon/internal/agent//`, its + native configuration in `internal/harnessconfig//`, its entry in + `internal/harnessconfig/builtin/catalog.json`, its discovery and registration in + `apps/parsar-daemon/internal/cli/` (`agent_discovery.go`, `agent_registration.go` + and `native_harness.go`, plus per-Harness files such as `claude_sdk.go`), its + Runtime image in `services/agents-api/deploy//` and, when present, its + native package (`packages/claude-sdk-adapter/`, `packages/mcode-harness/`). +- **Model provider:** nothing while it speaks a model protocol that + `internal/modelprovider` defines and a Harness declares; a new model protocol is a + protocol change. + +Rules for every adapter: + +- A new Sandbox Provider, Harness, model provider or vendor feature adds no Core + execution path, store table or column, migration, deployment or configuration + field, API field or Web UI specific to that vendor or Harness. - When the protocol cannot express what an adapter needs, change the protocol as a change of its own: edit its code and document, update every implementation, and have it reviewed on its own. Never add an optional side interface for one implementation. -- Example: making one sandbox vendor pause idle compute is that vendor's Provider's - job, done behind the existing lifecycle operations. A vendor-specific pause - interface, a new Core resume path, pause receipts in the store and a vendor idle - setting in the deployment go beyond an adapter change. +- Example: a vendor that can pause idle compute implements the declared `Suspend` + and `Resume` operations of `CheckpointProvider` in its own Provider; that is an + adapter change. A vendor-only pause interface, a Core path for that vendor, + vendor receipts in the store or a vendor idle setting in the deployment is not. +- Each Harness runs its own native model and tool loop through a maintained + upstream SDK or native protocol. Never build a second executor, a hand-written + model/tool loop or a general-purpose compatibility framework to fabricate parity. + The public API and persistence never depend on one engine's native item types. Each component owns one part of execution: | Component | Owns | | --- | --- | -| Core | Durable Session and Turn state, admission and scheduling | -| Sandbox Provider | Compute selection, creation, bootstrap, renewal and reclamation | -| Runtime | Preparation inside the Environment (files, tool configuration, packages, capabilities) and execution | +| Core | Durable Session, Turn, Environment and allocation state; admission, placement and scheduling | +| Sandbox Provider | Compute creation, bootstrap, renewal and reclamation | +| Runtime | Preparation, execution and recovery inside the Environment | | Harness adapter | Translation of the common execution contract into native operations | - Executor and compute lifetimes are separate; see @@ -101,18 +116,23 @@ Each component owns one part of execution: | Category | Home | Written by | | --- | --- | --- | -| Process settings | `/config.json`; the installer defaults `` to `~/.oac/core` | The operator, applied with `oac apply` | +| Process settings | `/config.json`; the installer defaults `` to `~/.oac/core` | The operator, Web domain setup or `oac domain`; `oac apply` applies them | | Derived process files | `/generated/` | `oac apply` only | -| Secrets | `/secrets/`, one file per secret | The installer and `oac` commands | -| Installation identity and local provider receipts | `/state.json` and `/state/` | The installer tools and Core's provider helpers | -| Runtime settings | Core's PostgreSQL | Web or `/core/v1` | -| Execution data | Core's PostgreSQL | Core, through its APIs | -| Node configuration and identity | `~/.oac/nodes//` in the node account's home | The node installer and node | -| Self-hosted executor | `~/.oac/environments//` | The native installer and daemon | -| Runtime daemon state | `~/.oac/daemon//`; `OAC_RUNTIME_HOME` replaces `~/.oac` | The daemon | -| Build output | `~/.oac/build/`; `OAC_DEV_HOME` replaces `~/.oac` | `make` targets | +| Secrets and installation identity | `/secrets/`, one file per secret; `/state.json` | The installer and `oac` commands | +| Provider helper state | `/state/` | Core's provider helpers | +| Managed HTTPS | `/ingress/`: domain status, certificates and control sockets | `oac` and the managed ingress | +| Installed release files | `/oac`, `/native/`, `/node-payload/`; verified bundles in `~/.oac/releases/` | The installer | +| Runtime settings and execution data | Core's PostgreSQL | Web or `/core/v1` for settings; Core, through its APIs, for execution data | +| Node identity, configuration and storage | `~/.oac/nodes//` and microsandbox storage in `~/.oac/m//`, in the node account's home | The node installer and node | +| Daemon settings | `OAC_RUNTIME_*` in the daemon's process environment | The Runtime image, the Sandbox Provider at launch, or `oac-daemon start` from `daemon/installation.json` on a self-hosted machine | +| Runtime state | `~/.oac/daemon/` (Environment binding, installation, executor credential, sessions, scratch and capability installations; connection state per profile in `daemon//`) and adapter state in `~/.oac/runtime//` | The daemon and its adapters | +| Self-hosted executors | `~/.oac/environments//`, each its own Runtime home | The native installer and daemon | +| Build output and caches | `~/.oac/build/`; CI caches in `~/.oac/cache/` | `make` targets; CI | | Test artifacts | Under `~/.oac/` | Tests and acceptance runs | +`OAC_RUNTIME_HOME` replaces `~/.oac` for Runtime state and self-hosted executors; +`OAC_DEV_HOME` replaces it for build output. + ### Pre-release: no compatibility layers OpenAgentCore is pre-release. Replace superseded interfaces, execution paths, files @@ -121,6 +141,25 @@ migration for retired behavior unless an explicit upgrade contract requires it. Keep the pinned official public protocol, valid data and still-used, verified infrastructure; do not rewrite working infrastructure only to rename it. +### Known gaps + +Existing code that breaks these rules is a gap, not a precedent. Do not copy these +patterns; a change that touches one of them moves it toward the rule. + +- Multi-file protocols: every row of the boundary table that lists more than one + file, a glob or a directory. +- Harness support by type assertion: `apps/parsar-daemon/internal/dispatch/workspace_read.go` + selects workspace file reads and directory listings by asserting `WorkspaceReader` + and `WorkspaceDirectoryLister` instead of reading a declaration; `dispatch/steering.go` + reports a declared but missing `Steerer` as unsupported. +- Per-Harness profiles inside Core: `services/agents-api/internal/engine/.go` + (`claude.go`, `codex.go`, `mcode.go`). +- Vendor configuration outside the adapter: `sandbox.Selection` has an `E2B` field + (`services/agents-api/internal/sandbox/selection.go`) with matching store + columns, API fields and operator-client types, as + [Register the provider kind](docs/sandbox-provider.md#register-the-provider-kind) + directs for new Provider fields. + ## Documentation - One fact, one place. Link to the owning document instead of restating it. The @@ -133,6 +172,7 @@ infrastructure; do not rewrite working infrastructure only to rename it. numbers, "retired", "former", "this candidate") and task chronology. - Delete obsolete, historical and duplicate documentation outright. Qualification evidence stays only while it qualifies current behavior. +- Do not hard-wrap prose. Write each paragraph, list item and blockquote on one line; editors wrap it for display. - Write documentation and code comments in English. The root README also has a Chinese version; user-facing product copy may be bilingual. - Markdown in `docs/`, component guides and `contracts/` is the authored source. @@ -145,9 +185,6 @@ infrastructure; do not rewrite working infrastructure only to rename it. - [CONTRIBUTING.md](CONTRIBUTING.md): workflow, independent review, required checks and naming. -- [docs/development.md](docs/development.md): setup, the repository map and - [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). +- [Develop OpenAgentCore](docs/development.md): setup, the repository map, focused + checks and [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). - [API index](docs/api/README.md): each route's caller and credential. -- Run `make sqlc-generate` after query changes and `make openapi` after handler - changes. Review and commit the generated contracts with their source. -- Run `make check` before reporting completion. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26d1f2d3f..4fb5e86aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,22 +12,19 @@ Every other subject has one canonical owner, listed below. | Subject | Canonical source | | --- | --- | -| Design principles, protocol boundaries, storage layout and documentation rules | [AGENTS.md](AGENTS.md) | -| User concepts and authority | [Design principles](docs/design-principles.md) | +| Design principles, storage layout and documentation rules | [AGENTS.md](AGENTS.md) | +| Protocol boundaries: each boundary's protocol code and document | [AGENTS.md](AGENTS.md#protocols-at-every-boundary) | +| User concepts and authority | [Concepts and ownership](docs/design-principles.md) | | Architecture overview and diagrams (a map that links to the owners below) | [Architecture](docs/architecture.md) | -| Developer setup, repository map and extension boundaries | [Develop OpenAgentCore](docs/development.md) | +| Developer setup, repository map and focused checks | [Develop OpenAgentCore](docs/development.md) | | API callers, credentials and route inventory | [API index](docs/api/README.md) | | Public wire types and qualified behavior | [Agents API contracts](contracts/agents-api/README.md), [pinned upstream](contracts/agents-api/upstream.json), and linked operation contracts | | Core service implementation constraints | [Agents API implementation constraints](services/agents-api/IMPLEMENTATION.md) and [service README](services/agents-api/README.md) | -| Provider-to-Runtime startup input | [Runtime bootstrap](docs/runtime-bootstrap.md) | -| Runtime messages, Executor/Turn lifetimes, receipts and failure ownership | [Core–Runtime protocol](docs/runtime-protocol.md) | | Environment ownership and capability preparation (Skills, Plugins, MCP, `packages.system`) | [Environments](contracts/agents-api/environments.md) | -| Adding a Harness (steps) | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | | Built-in Harness identifiers, configuration/profile bindings and display names | `internal/harnessconfig/builtin/catalog.json` and its [generated reference](contracts/agents-api/harness-catalog.md) | | Effective MCP bindings and credential authority | [Environment MCP](contracts/agents-api/environments.md#skills-plugins-and-environment-mcp) and `apps/parsar-daemon/internal/agent/mcp_binding.go` | | Harness qualification and acceptance | [Harness integration](contracts/agents-api/harnesses.md) | | Harness selection and Agent defaults | [Harness selection](contracts/agents-api/harness-selection.md) | -| Adding a Sandbox Provider | [Sandbox Provider guide](docs/sandbox-provider.md) | | Provider selection, sandbox deployment and E2B setup | [Sandbox deployment](contracts/agents-api/sandbox-deployment.md) | | Hosted sandbox nodes | [Hosted sandbox manager](services/agents-api/HOSTED-SANDBOX-MANAGER.md) | | Claude private bridge and Runtime artifact | [Claude SDK adapter](packages/claude-sdk-adapter/README.md) | @@ -75,9 +72,8 @@ databases, credentials and migrations. The product uses Core exclusively; it has the user before changing its semantics. Explicit unsupported enablement rejects; ordinary requests retain native behavior with any official default discrepancy recorded in the coverage ledger. In particular, native programmatic tool calling - is not currently qualified as the official default-on behavior. Do not build - a separate executor or model loop to fabricate parity. This does not relax - authentication, isolation, credential protection or data consistency. + is not currently qualified as the official default-on behavior. This does not + relax authentication, isolation, credential protection or data consistency. - Pin upstream source and SDK versions in `contracts/agents-api/upstream.json`. Use official SDKs for clients and reuse upstream types or schemas where suitable. SDK deserialization alone is not server validation or proof of compatibility: @@ -95,16 +91,13 @@ databases, credentials and migrations. The product uses Core exclusively; it has coverage in `contracts/agents-api/README.md` until the complete target is verified. Reconcile current coverage summaries with merged routes and recorded acceptance; distinguish accepted profiles, partial implementation, missing operations and - unverified semantics. Keep each evidence record at its original scope. Handler - counts are not compatibility percentages, and an active provider probe is not - deployment qualification. + unverified semantics. Handler counts are not compatibility percentages, and an + active provider probe is not deployment qualification. - Qualify public workflows through the common Runtime contract and Harness adapter; direct native probes establish feasibility only. - Native workspace execution must use the declared Environment directory; a separate native history/configuration directory is not a workspace. The public API and persistence/application core must not interpret Parsar product payloads. - Prefer maintained upstream SDKs and native execution protocols over a second - hand-written model/tool loop or a general-purpose compatibility framework. - Verify an independent official-client workflow before a Parsar integration. Parsar uses the same public contract as any other client, with no privileged endpoint or direct execution-table access. An OpenAI endpoint is a possible @@ -159,7 +152,7 @@ databases, credentials and migrations. The product uses Core exclusively; it has 3. Make only the changes that scope needs; keep unrelated refactors separate. When documents conflict, apply the latest explicit user decision and update the -affected current guidance. Historical evidence does not override it. +affected current guidance. Recorded evidence does not override it. If requirements are unresolved, object ownership is unclear, or a design would need parallel compatibility paths, raise the issue with a concrete @@ -284,8 +277,8 @@ allocations or accepts node deployments without a valid specification. Keep the original Core responsible for unresolved resources; see the [operator boundary](services/agents-api/HOSTED-SANDBOX-MANAGER.md#historical-installations). Use this release's template builder for -new E2B templates. Landed migrations and historical evidence stay as repository -history; ordinary current-version database initialization uses the migration runner. +new E2B templates. Ordinary current-version database initialization uses the +migration runner. The dormant Pi adapter keeps its `parsar` provider slug because the separate Parsar product pins model selections to that identity. This is a product @@ -321,6 +314,6 @@ These identities stay unchanged: - persisted credential encryption domains and native-session resume keys, so existing data can be decrypted and Sessions can resume. -Conversion inputs, retirement diagnostics and historical evidence must still -name the identifiers they reject. Historical migration files keep their original -identifiers; current examples use the new names. +Conversion inputs, retirement diagnostics and evidence records must still name +the identifiers they reject. Landed migrations keep their original identifiers; +current examples use the new names. diff --git a/scripts/name-allowlist.json b/scripts/name-allowlist.json index 8a13d8b23..2e3688572 100644 --- a/scripts/name-allowlist.json +++ b/scripts/name-allowlist.json @@ -524,11 +524,6 @@ "regex": "parsar-core-runtime@sha256:", "reason": "The literal is a rejected legacy Runtime prefix fixture, not an accepted deployment reference." }, - { - "path": "AGENTS.md", - "regex": "behind Parsar", - "reason": "These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." - }, { "path": "CONTRIBUTING.md", "regex": "copied from Parsar at|in Parsar\\.|apps/parsar/|Parsar is an ordinary client|Parsar integration|Parsar uses|Parsar owns|Parsar marketplace|belong to Parsar|Parsar retains|Parsar Agents|`parsar` provider slug", From 3b329ccbdbbbc1a23d7d0862a6497e608a9458b1 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 06:48:20 +0000 Subject: [PATCH 3/5] docs: unwrap prose in AGENTS.md, CONTRIBUTING.md and docs/architecture.md --- AGENTS.md | 158 +++++++-------------------- CONTRIBUTING.md | 247 ++++++++++--------------------------------- docs/architecture.md | 93 ++++------------ 3 files changed, 116 insertions(+), 382 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 85e1f47be..c4f5d23a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,16 @@ # OpenAgentCore development -This file holds the design rules every change follows. -[Working in this repository](#working-in-this-repository) links to everything else. +This file holds the design rules every change follows. [Working in this repository](#working-in-this-repository) links to everything else. ## Design principles -OpenAgentCore is protocol-first and modular. Core orchestrates operations that -protocols define. Sandbox Providers, Runtimes, Harnesses and model providers are -replaceable implementations of those protocols; user-owned machines, E2B, Docker -and microsandbox expose the same execution protocol. +OpenAgentCore is protocol-first and modular. Core orchestrates operations that protocols define. Sandbox Providers, Runtimes, Harnesses and model providers are replaceable implementations of those protocols; user-owned machines, E2B, Docker and microsandbox expose the same execution protocol. ### Protocols at every boundary -- Each boundary between components has exactly one protocol: one code file - (interface, wire types and validators) and one document. Change the code and the - document together, and update every implementation in the same change. -- Protocols are deterministic. Declare each operation explicitly and type each - outcome. Declare support; never discover it through optional-interface type - assertions, name checks or implicit fallbacks. An unsupported operation returns - an explicit typed error. -- A component joins the system only by implementing a protocol. It gets no private - entry point, side channel or path selected by its name. +- Each boundary between components has exactly one protocol: one code file (interface, wire types and validators) and one document. Change the code and the document together, and update every implementation in the same change. +- Protocols are deterministic. Declare each operation explicitly and type each outcome. Declare support; never discover it through optional-interface type assertions, name checks or implicit fallbacks. An unsupported operation returns an explicit typed error. +- A component joins the system only by implementing a protocol. It gets no private entry point, side channel or path selected by its name. | Boundary | Protocol code | Protocol doc | | --- | --- | --- | @@ -34,50 +24,22 @@ and microsandbox expose the same execution protocol. | Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go`, with result types and errors in `apps/parsar-daemon/internal/agent/*.go`; `internal/harnessconfig/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | | Harness–Model provider | `internal/modelprovider/config.go`, `internal/harnessconfig/provider.go` | [Model execution](contracts/agents-api/model-execution.md) | -`make openapi` generates the three OpenAPI files from the Go types and the handler -annotations in `services/agents-api/`; never edit them by hand. Rows that list more -than one file, a glob or a directory do not meet the single-file rule yet; do not -add files to them. +`make openapi` generates the three OpenAPI files from the Go types and the handler annotations in `services/agents-api/`; never edit them by hand. Rows that list more than one file, a glob or a directory do not meet the single-file rule yet; do not add files to them. ### Complexity stays in the adapter -New complexity lives in the adapter that needs it and never spreads outward. A new -implementation adds or changes only these files. Directory names differ per -Harness: Claude uses `claude_sdk`, `claudesdk` and `claude`. - -- **Sandbox Provider:** its package `services/agents-api/internal/sandbox//`, - its construction in `services/agents-api/internal/sandbox/providers/.go` - and its entry in `services/agents-api/internal/sandbox/providers/registry.go`; - when present, its helper in `services/agents-api/tools/-provider/` and its - operator material in `services/agents-api/deploy//`. -- **Harness:** its adapter in `apps/parsar-daemon/internal/agent//`, its - native configuration in `internal/harnessconfig//`, its entry in - `internal/harnessconfig/builtin/catalog.json`, its discovery and registration in - `apps/parsar-daemon/internal/cli/` (`agent_discovery.go`, `agent_registration.go` - and `native_harness.go`, plus per-Harness files such as `claude_sdk.go`), its - Runtime image in `services/agents-api/deploy//` and, when present, its - native package (`packages/claude-sdk-adapter/`, `packages/mcode-harness/`). -- **Model provider:** nothing while it speaks a model protocol that - `internal/modelprovider` defines and a Harness declares; a new model protocol is a - protocol change. +New complexity lives in the adapter that needs it and never spreads outward. A new implementation adds or changes only these files. Directory names differ per Harness: Claude uses `claude_sdk`, `claudesdk` and `claude`. + +- **Sandbox Provider:** its package `services/agents-api/internal/sandbox//`, its construction in `services/agents-api/internal/sandbox/providers/.go` and its entry in `services/agents-api/internal/sandbox/providers/registry.go`; when present, its helper in `services/agents-api/tools/-provider/` and its operator material in `services/agents-api/deploy//`. +- **Harness:** its adapter in `apps/parsar-daemon/internal/agent//`, its native configuration in `internal/harnessconfig//`, its entry in `internal/harnessconfig/builtin/catalog.json`, its discovery and registration in `apps/parsar-daemon/internal/cli/` (`agent_discovery.go`, `agent_registration.go` and `native_harness.go`, plus per-Harness files such as `claude_sdk.go`), its Runtime image in `services/agents-api/deploy//` and, when present, its native package (`packages/claude-sdk-adapter/`, `packages/mcode-harness/`). +- **Model provider:** nothing while it speaks a model protocol that `internal/modelprovider` defines and a Harness declares; a new model protocol is a protocol change. Rules for every adapter: -- A new Sandbox Provider, Harness, model provider or vendor feature adds no Core - execution path, store table or column, migration, deployment or configuration - field, API field or Web UI specific to that vendor or Harness. -- When the protocol cannot express what an adapter needs, change the protocol as a - change of its own: edit its code and document, update every implementation, and - have it reviewed on its own. Never add an optional side interface for one - implementation. -- Example: a vendor that can pause idle compute implements the declared `Suspend` - and `Resume` operations of `CheckpointProvider` in its own Provider; that is an - adapter change. A vendor-only pause interface, a Core path for that vendor, - vendor receipts in the store or a vendor idle setting in the deployment is not. -- Each Harness runs its own native model and tool loop through a maintained - upstream SDK or native protocol. Never build a second executor, a hand-written - model/tool loop or a general-purpose compatibility framework to fabricate parity. - The public API and persistence never depend on one engine's native item types. +- A new Sandbox Provider, Harness, model provider or vendor feature adds no Core execution path, store table or column, migration, deployment or configuration field, API field or Web UI specific to that vendor or Harness. +- When the protocol cannot express what an adapter needs, change the protocol as a change of its own: edit its code and document, update every implementation, and have it reviewed on its own. Never add an optional side interface for one implementation. +- Example: a vendor that can pause idle compute implements the declared `Suspend` and `Resume` operations of `CheckpointProvider` in its own Provider; that is an adapter change. A vendor-only pause interface, a Core path for that vendor, vendor receipts in the store or a vendor idle setting in the deployment is not. +- Each Harness runs its own native model and tool loop through a maintained upstream SDK or native protocol. Never build a second executor, a hand-written model/tool loop or a general-purpose compatibility framework to fabricate parity. The public API and persistence never depend on one engine's native item types. Each component owns one part of execution: @@ -88,31 +50,17 @@ Each component owns one part of execution: | Runtime | Preparation, execution and recovery inside the Environment | | Harness adapter | Translation of the common execution contract into native operations | -- Executor and compute lifetimes are separate; see - [Executor and Turn lifetimes](docs/runtime-protocol.md#executor-and-turn-lifetimes). - Capability preparation follows [Environments](contracts/agents-api/environments.md#runtime-capability-preparation), - and isolation belongs to the outer Environment; see - [Runtime and outer isolation](docs/design-principles.md#runtime-and-outer-isolation). -- Fix shared lifecycle, admission, cancellation, reuse and performance problems in - the common flow, never in branches selected by a Harness, Runtime or vendor name. -- Express compatibility through declared capabilities and validate each selected - combination explicitly. Reject an unsupported combination with an explicit error. - Never substitute another implementation or give a capability a different meaning - per vendor. -- Core preparation and execution never branch on operating system or Environment - source. Platform support requires native CI builds and automated tests; - cross-compilation alone is insufficient. -- Each rule has one authored definition. Generate cross-language projections from - it or check them against shared fixtures. +- Executor and compute lifetimes are separate; see [Executor and Turn lifetimes](docs/runtime-protocol.md#executor-and-turn-lifetimes). Capability preparation follows [Environments](contracts/agents-api/environments.md#runtime-capability-preparation), and isolation belongs to the outer Environment; see [Runtime and outer isolation](docs/design-principles.md#runtime-and-outer-isolation). +- Fix shared lifecycle, admission, cancellation, reuse and performance problems in the common flow, never in branches selected by a Harness, Runtime or vendor name. +- Express compatibility through declared capabilities and validate each selected combination explicitly. Reject an unsupported combination with an explicit error. Never substitute another implementation or give a capability a different meaning per vendor. +- Core preparation and execution never branch on operating system or Environment source. Platform support requires native CI builds and automated tests; cross-compilation alone is insufficient. +- Each rule has one authored definition. Generate cross-language projections from it or check them against shared fixtures. ### One home for each setting and datum -- Write each setting and each piece of data in one place and read it from that - place. Keep no second copy, no environment-variable or file fallback and no alias. -- Keep configuration files together. Where that is impossible, group them by - category. Never scatter them. -- A new setting joins one of the categories below and lives beside its peers. - [Configuration](docs/configuration.md) documents the settings themselves. +- Write each setting and each piece of data in one place and read it from that place. Keep no second copy, no environment-variable or file fallback and no alias. +- Keep configuration files together. Where that is impossible, group them by category. Never scatter them. +- A new setting joins one of the categories below and lives beside its peers. [Configuration](docs/configuration.md) documents the settings themselves. | Category | Home | Written by | | --- | --- | --- | @@ -130,61 +78,35 @@ Each component owns one part of execution: | Build output and caches | `~/.oac/build/`; CI caches in `~/.oac/cache/` | `make` targets; CI | | Test artifacts | Under `~/.oac/` | Tests and acceptance runs | -`OAC_RUNTIME_HOME` replaces `~/.oac` for Runtime state and self-hosted executors; -`OAC_DEV_HOME` replaces it for build output. +`OAC_RUNTIME_HOME` replaces `~/.oac` for Runtime state and self-hosted executors; `OAC_DEV_HOME` replaces it for build output. ### Pre-release: no compatibility layers -OpenAgentCore is pre-release. Replace superseded interfaces, execution paths, files -and documents outright. Keep no version fallback, compatibility shim, alias or -migration for retired behavior unless an explicit upgrade contract requires it. -Keep the pinned official public protocol, valid data and still-used, verified -infrastructure; do not rewrite working infrastructure only to rename it. +OpenAgentCore is pre-release. Replace superseded interfaces, execution paths, files and documents outright. Keep no version fallback, compatibility shim, alias or migration for retired behavior unless an explicit upgrade contract requires it. Keep the pinned official public protocol, valid data and still-used, verified infrastructure; do not rewrite working infrastructure only to rename it. ### Known gaps -Existing code that breaks these rules is a gap, not a precedent. Do not copy these -patterns; a change that touches one of them moves it toward the rule. - -- Multi-file protocols: every row of the boundary table that lists more than one - file, a glob or a directory. -- Harness support by type assertion: `apps/parsar-daemon/internal/dispatch/workspace_read.go` - selects workspace file reads and directory listings by asserting `WorkspaceReader` - and `WorkspaceDirectoryLister` instead of reading a declaration; `dispatch/steering.go` - reports a declared but missing `Steerer` as unsupported. -- Per-Harness profiles inside Core: `services/agents-api/internal/engine/.go` - (`claude.go`, `codex.go`, `mcode.go`). -- Vendor configuration outside the adapter: `sandbox.Selection` has an `E2B` field - (`services/agents-api/internal/sandbox/selection.go`) with matching store - columns, API fields and operator-client types, as - [Register the provider kind](docs/sandbox-provider.md#register-the-provider-kind) - directs for new Provider fields. +Existing code that breaks these rules is a gap, not a precedent. Do not copy these patterns; a change that touches one of them moves it toward the rule. + +- Multi-file protocols: every row of the boundary table that lists more than one file, a glob or a directory. +- Harness support by type assertion: `apps/parsar-daemon/internal/dispatch/workspace_read.go` selects workspace file reads and directory listings by asserting `WorkspaceReader` and `WorkspaceDirectoryLister` instead of reading a declaration; `dispatch/steering.go` reports a declared but missing `Steerer` as unsupported. +- Per-Harness profiles inside Core: `services/agents-api/internal/engine/.go` (`claude.go`, `codex.go`, `mcode.go`). +- Vendor configuration outside the adapter: `sandbox.Selection` has an `E2B` field (`services/agents-api/internal/sandbox/selection.go`) with matching store columns, API fields and operator-client types, as [Register the provider kind](docs/sandbox-provider.md#register-the-provider-kind) directs for new Provider fields. ## Documentation -- One fact, one place. Link to the owning document instead of restating it. The - owner map is [Documentation ownership](CONTRIBUTING.md#documentation-ownership). +- One fact, one place. Link to the owning document instead of restating it. The owner map is [Documentation ownership](CONTRIBUTING.md#documentation-ownership). - Keep a subject together in one document or section. -- Give each document one audience and one job. Order it for reading: what the - subject is, how to do the task, then reference detail. -- Write plainly and helpfully. State what the system does and what the reader does. - Leave out filler, hedging, defensive negations, process history (PR or design - numbers, "retired", "former", "this candidate") and task chronology. -- Delete obsolete, historical and duplicate documentation outright. Qualification - evidence stays only while it qualifies current behavior. +- Give each document one audience and one job. Order it for reading: what the subject is, how to do the task, then reference detail. +- Write plainly and helpfully. State what the system does and what the reader does. Leave out filler, hedging, defensive negations, process history (PR or design numbers, "retired", "former", "this candidate") and task chronology. +- Delete obsolete, historical and duplicate documentation outright. Qualification evidence stays only while it qualifies current behavior. - Do not hard-wrap prose. Write each paragraph, list item and blockquote on one line; editors wrap it for display. -- Write documentation and code comments in English. The root README also has a - Chinese version; user-facing product copy may be bilingual. -- Markdown in `docs/`, component guides and `contracts/` is the authored source. - Generated copies, such as the `apps/docs` content and generated references, are - never edited by hand: change the source and regenerate. -- Update the owning document in the same branch as the rule, boundary, workflow or - generated contract it describes. +- Write documentation and code comments in English. The root README also has a Chinese version; user-facing product copy may be bilingual. +- Markdown in `docs/`, component guides and `contracts/` is the authored source. Generated copies, such as the `apps/docs` content and generated references, are never edited by hand: change the source and regenerate. +- Update the owning document in the same branch as the rule, boundary, workflow or generated contract it describes. ## Working in this repository -- [CONTRIBUTING.md](CONTRIBUTING.md): workflow, independent review, required checks - and naming. -- [Develop OpenAgentCore](docs/development.md): setup, the repository map, focused - checks and [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). +- [CONTRIBUTING.md](CONTRIBUTING.md): workflow, independent review, required checks and naming. +- [Develop OpenAgentCore](docs/development.md): setup, the repository map, focused checks and [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). - [API index](docs/api/README.md): each route's caller and credential. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4fb5e86aa..9a7962c52 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,6 @@ # Contributing to OpenAgentCore -Start with [Develop OpenAgentCore](docs/development.md) for checkout, toolchains, -the repository map and focused checks. [AGENTS.md](AGENTS.md) owns the design -principles and documentation rules. This guide owns how to work in the repository: -documentation ownership, the repository boundary, workflow and review, required -checks and naming. +Start with [Develop OpenAgentCore](docs/development.md) for checkout, toolchains, the repository map and focused checks. [AGENTS.md](AGENTS.md) owns the design principles and documentation rules. 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. @@ -37,108 +33,38 @@ Every other subject has one canonical owner, listed below. ## Repository boundary -This repository is the standalone execution substrate copied from Parsar at the -revision in `provenance/source.json`. It holds the API and its migrations, the -Runtime protocol and daemon, Harness adapters, shared execution packages, the -standalone Core Web console and build/test tools. +This repository is the standalone execution substrate copied from Parsar at the revision in `provenance/source.json`. It holds the API and its migrations, the Runtime protocol and daemon, Harness adapters, shared execution packages, the standalone Core Web console and build/test tools. -Product users, workspaces, model catalogs, business assets, the Parsar product -Web, product API and product migrations remain in Parsar. Do not import -`server/`, `apps/parsar/`, product CLI/plugin packages or their deployment stack. +Product users, workspaces, model catalogs, business assets, the Parsar product Web, product API and product migrations remain in Parsar. Do not import `server/`, `apps/parsar/`, product CLI/plugin packages or their deployment stack. -Preserve copied Runtime and protocol behavior. Existing Go import paths stay -unchanged and do not require fetching the original repository. The source -snapshot and per-file hashes are an audit trail; future Core development need -not preserve them. Do not automatically sync or delete the original repository's Core. +Preserve copied Runtime and protocol behavior. Existing Go import paths stay unchanged and do not require fetching the original repository. The source snapshot and per-file hashes are an audit trail; future Core development need not preserve them. Do not automatically sync or delete the original repository's Core. ### Product and execution service separation -Agents API is the primary infrastructure deliverable. Parsar is an ordinary client -and example application; its feature backlog must not dictate the execution -service's public protocol or internal model. Agents API must build, deploy and run -without the Parsar product service, frontend or database. An optional Compose -deployment may install both services with one PostgreSQL instance, but separate -databases, credentials and migrations. The product uses Core exclusively; it has no native daemon or HTTP Agent fallback. +Agents API is the primary infrastructure deliverable. Parsar is an ordinary client and example application; its feature backlog must not dictate the execution service's public protocol or internal model. Agents API must build, deploy and run without the Parsar product service, frontend or database. An optional Compose deployment may install both services with one PostgreSQL instance, but separate databases, credentials and migrations. The product uses Core exclusively; it has no native daemon or HTTP Agent fallback. #### Design and compatibility requirements -- The complete pinned `openai/openai-python` `beta/agents` protocol is the target, - including its referenced resources and types. Match paths, methods, headers, - field presence, nullability, discriminators, defaults, status transitions, - pagination, errors and streaming behavior. Engine limitations are implementation - gaps to solve, not grounds for narrowing or redefining the upstream contract. -- Preserve qualified native capability differences across harnesses. If a material - difference from the official API has no clear mapping, pause that part and ask - the user before changing its semantics. Explicit unsupported enablement rejects; - ordinary requests retain native behavior with any official default discrepancy - recorded in the coverage ledger. In particular, native programmatic tool calling - is not currently qualified as the official default-on behavior. This does not - relax authentication, isolation, credential protection or data consistency. -- Pin upstream source and SDK versions in `contracts/agents-api/upstream.json`. - Use official SDKs for clients and reuse upstream types or schemas where suitable. - SDK deserialization alone is not server validation or proof of compatibility: - test raw HTTP payloads and observable workflows as well. Synthetic data and mock - model responses may support controlled tests; live execution acceptance must - call a real model API through the service, daemon and harness. A real daemon - with a synthetic model does not constitute live model validation. Keep provider - credentials in private test configuration, outside source, logs and task records. - Record unspecified or unverified behavior explicitly; never invent official - semantics. When current documentation adds operations or fields absent from the - fixed baseline, queue a protocol upgrade instead of silently implementing a new - version. Owned-resource live probes can qualify status codes and wire details - left unspecified by the SDK; retain request evidence and distinguish observations - from guaranteed or fully covered behavior. Track partial - coverage in `contracts/agents-api/README.md` until the complete target is verified. - Reconcile current coverage summaries with merged routes and recorded acceptance; - distinguish accepted profiles, partial implementation, missing operations and - unverified semantics. Handler counts are not compatibility percentages, and an - active provider probe is not deployment qualification. -- Qualify public workflows through the common Runtime contract and Harness - adapter; direct native probes establish feasibility only. -- Native workspace execution must use the declared Environment directory; a - separate native history/configuration directory is not a workspace. The public - API and persistence/application core must not interpret Parsar product payloads. -- Verify an independent official-client workflow before a Parsar integration. - Parsar uses the same public contract as any other client, with no privileged - endpoint or direct execution-table access. An OpenAI endpoint is a possible - client target only where the requested capabilities and credentials support it. - -- Parsar owns users, workspaces, business authorization, Agent/Team definitions, - capabilities, product conversations, IM/sharing, approval decisions and billing. -- Agents API owns protocol saved Agents, execution sessions/turns, effective - configuration snapshots, dispatch/cancel, environments, vaults, raw usage, - pending interactions, protocol subagents and durable events. Protocol saved - Agents/vaults are execution resources, not Parsar marketplace or business roles. - Neither service reads the other's tables. Parsar uses a versioned client contract. -- A product conversation may map to several execution sessions. An execution - session is distinct from a live daemon socket, process or sandbox. Native engine - session identifiers belong to the execution service. -- Establish single-Agent execution, approval, cancellation, idempotent submission, - persisted recovery queries before Team orchestration. The upstream SSE stream - is live-only; recover through Session/Turn/Items reads. Any additional product - cursor replay must be documented as an extension, not upstream semantics. - Team definitions, management and orchestration belong to Parsar. Agents API - establishes single-Agent execution first; business Team loops are deferred. - This does not exclude upstream `multi_agent` configuration or subagent resources - from protocol coverage. Future business Team orchestration directly depends on - `openai/openai-agents-python` in Parsar. -- Daemon Skill/SP authoring remains a product operation: forward through a scoped - product callback with the original requester and workspace checks. A runtime - credential alone must not grant business write permissions. +- The complete pinned `openai/openai-python` `beta/agents` protocol is the target, including its referenced resources and types. Match paths, methods, headers, field presence, nullability, discriminators, defaults, status transitions, pagination, errors and streaming behavior. Engine limitations are implementation gaps to solve, not grounds for narrowing or redefining the upstream contract. +- Preserve qualified native capability differences across harnesses. If a material difference from the official API has no clear mapping, pause that part and ask the user before changing its semantics. Explicit unsupported enablement rejects; ordinary requests retain native behavior with any official default discrepancy recorded in the coverage ledger. In particular, native programmatic tool calling is not currently qualified as the official default-on behavior. This does not relax authentication, isolation, credential protection or data consistency. +- Pin upstream source and SDK versions in `contracts/agents-api/upstream.json`. Use official SDKs for clients and reuse upstream types or schemas where suitable. SDK deserialization alone is not server validation or proof of compatibility: test raw HTTP payloads and observable workflows as well. Synthetic data and mock model responses may support controlled tests; live execution acceptance must call a real model API through the service, daemon and harness. A real daemon with a synthetic model does not constitute live model validation. Keep provider credentials in private test configuration, outside source, logs and task records. Record unspecified or unverified behavior explicitly; never invent official semantics. When current documentation adds operations or fields absent from the fixed baseline, queue a protocol upgrade instead of silently implementing a new version. Owned-resource live probes can qualify status codes and wire details left unspecified by the SDK; retain request evidence and distinguish observations from guaranteed or fully covered behavior. Track partial coverage in `contracts/agents-api/README.md` until the complete target is verified. Reconcile current coverage summaries with merged routes and recorded acceptance; distinguish accepted profiles, partial implementation, missing operations and unverified semantics. Handler counts are not compatibility percentages, and an active provider probe is not deployment qualification. +- Qualify public workflows through the common Runtime contract and Harness adapter; direct native probes establish feasibility only. +- Native workspace execution must use the declared Environment directory; a separate native history/configuration directory is not a workspace. The public API and persistence/application core must not interpret Parsar product payloads. +- Verify an independent official-client workflow before a Parsar integration. Parsar uses the same public contract as any other client, with no privileged endpoint or direct execution-table access. An OpenAI endpoint is a possible client target only where the requested capabilities and credentials support it. + +- Parsar owns users, workspaces, business authorization, Agent/Team definitions, capabilities, product conversations, IM/sharing, approval decisions and billing. +- Agents API owns protocol saved Agents, execution sessions/turns, effective configuration snapshots, dispatch/cancel, environments, vaults, raw usage, pending interactions, protocol subagents and durable events. Protocol saved Agents/vaults are execution resources, not Parsar marketplace or business roles. Neither service reads the other's tables. Parsar uses a versioned client contract. +- A product conversation may map to several execution sessions. An execution session is distinct from a live daemon socket, process or sandbox. Native engine session identifiers belong to the execution service. +- Establish single-Agent execution, approval, cancellation, idempotent submission, persisted recovery queries before Team orchestration. The upstream SSE stream is live-only; recover through Session/Turn/Items reads. Any additional product cursor replay must be documented as an extension, not upstream semantics. Team definitions, management and orchestration belong to Parsar. Agents API establishes single-Agent execution first; business Team loops are deferred. This does not exclude upstream `multi_agent` configuration or subagent resources from protocol coverage. Future business Team orchestration directly depends on `openai/openai-agents-python` in Parsar. +- Daemon Skill/SP authoring remains a product operation: forward through a scoped product callback with the original requester and workspace checks. A runtime credential alone must not grant business write permissions. ### Optional application example -`example/parsar/` is an optional, independently started Agent workbench. Its -[README](example/parsar/README.md) owns its product behavior. The boundary rules are: - -- It calls only public `/v1` APIs. Its Project key stays server-side; it never - holds a Core key or issues machine credentials. Core-only credential issuance - stays in the operator console. -- It may reuse product UI and 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. +`example/parsar/` is an optional, independently started Agent workbench. Its [README](example/parsar/README.md) owns its product behavior. The boundary rules are: + +- It calls only public `/v1` APIs. Its Project key stays server-side; it never holds a Core key or issues machine credentials. Core-only credential issuance stays in the operator console. +- It may reuse product UI and 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. @@ -147,55 +73,36 @@ databases, credentials and migrations. The product uses Core exclusively; it has ### Before you start 1. Record the requirements, acceptance criteria and scope. -2. Work in an isolated Git worktree on a feature branch and submit a PR. Do not - edit or commit implementation directly on `main`. +2. Work in an isolated Git worktree on a feature branch and submit a PR. Do not edit or commit implementation directly on `main`. 3. Make only the changes that scope needs; keep unrelated refactors separate. -When documents conflict, apply the latest explicit user decision and update the -affected current guidance. Recorded evidence does not override it. +When documents conflict, apply the latest explicit user decision and update the affected current guidance. Recorded evidence does not override it. -If requirements are unresolved, object ownership is unclear, or a design would -need parallel compatibility paths, raise the issue with a concrete -recommendation and tradeoffs before implementing it. Continue independent work -meanwhile. Do not silently preserve obsolete private designs. +If requirements are unresolved, object ownership is unclear, or a design would need parallel compatibility paths, raise the issue with a concrete recommendation and tradeoffs before implementing it. Continue independent work meanwhile. Do not silently preserve obsolete private designs. -Record unrelated findings without automatically starting them. Do not claim a -broader compatibility target is complete from one merged batch. +Record unrelated findings without automatically starting them. Do not claim a broader compatibility target is complete from one merged batch. ### Implementation conventions -- Search for existing formatters, parsers, validation and error mappers before - adding one. Keep one error mapper per API surface. -- Share frontend formatting and labels in `apps/web/src/lib/`; reuse components - and tokens. -- Split growing files at an existing ownership boundary instead of adding - unrelated responsibilities. -- 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). +- Search for existing formatters, parsers, validation and error mappers before adding one. Keep one error mapper per API surface. +- Share frontend formatting and labels in `apps/web/src/lib/`; reuse components and tokens. +- Split growing files at an existing ownership boundary instead of adding unrelated responsibilities. +- 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. -- New or changed routes identify their caller and credential in the - [API index](docs/api/README.md) and link their detailed contract. +- New or changed routes identify their caller and credential in the [API index](docs/api/README.md) and link their detailed contract. ### Review -1. After implementation and validation, have a fresh independent subagent review - the complete diff. -2. Give it only the requirements, acceptance criteria, boundaries, repository - path and comparison baseline. Do not give an implementation summary, - self-assessment or earlier findings. Explain these criteria to the user. +1. After implementation and validation, have a fresh independent subagent review the complete diff. +2. Give it only the requirements, acceptance criteria, boundaries, repository path and comparison baseline. Do not give an implementation summary, self-assessment or earlier findings. Explain these criteria to the user. 3. Fix substantiated in-scope findings, validate, then use another fresh reviewer. -4. If the cycle repeats, reassess design and scope before adding changes. Report - an unresolved blocker instead of broadening the task. +4. If the cycle repeats, reassess design and scope before adding changes. Report an unresolved blocker instead of broadening the task. Do not use `codex exec` as a substitute reviewer. ## 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). +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). ### Full gate @@ -207,9 +114,7 @@ Run `make check` before completion. It includes: - Core Web and TypeScript client checks, including fixture-only Playwright acceptance; - Claude SDK tests and packaging, and MiniMax companion checks; - the Core distribution and installer gates; -- `make check-example` for the optional application example (TypeScript, - proxy/persistence tests, build and fixture browser acceptance). Its synthetic - responses are not live model qualification. +- `make check-example` for the optional application example (TypeScript, proxy/persistence tests, build and fixture browser acceptance). Its synthetic responses are not live model qualification. It excludes Parsar product Web and server gates. @@ -220,37 +125,19 @@ It excludes Parsar product Web and server gates. | `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`: managed-provider tests create and drop -isolated `oac_*_tests` databases because provider identity is deployment-wide. -`PARSAR_AGENTS_API_TEST_DATABASE_URL` is retired; `make check-database` reports -its replacement when only the old name is set. Tests must not bypass the -production provider-switch guard. +The role needs `CREATE DATABASE`: managed-provider tests create and drop isolated `oac_*_tests` databases because provider identity is deployment-wide. `PARSAR_AGENTS_API_TEST_DATABASE_URL` is retired; `make check-database` reports its replacement when only the old name is set. Tests must not bypass the production provider-switch guard. ### Contract and schema rules -- `internal/harnessconfig/builtin/catalog.json` is the single authored public - Harness registration list. `make generate-harness-catalog` generates Go - configuration/profile registration, client identifiers/names and the reference; - `make openapi` derives the matching enums. `make check-harness-catalog` verifies - freshness in the full gate. Native configuration rules stay in their adapter - declarations; Core qualification and Runtime availability stay separate. - -- `make sqlc-generate` owns only `services/agents-api/internal/db/sqlc` - (sqlc v1.29.0). Do not rewrite landed migrations. -- The public protocol schema is `contracts/agents-api/openapi.yaml`. Preserve - its pinned types, coverage ledgers and official SDK/raw HTTP tests when - changing API behavior. Core changes keep the independent build and - official-client workflow. -- `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-agents-api`. +- `internal/harnessconfig/builtin/catalog.json` is the single authored public Harness registration list. `make generate-harness-catalog` generates Go configuration/profile registration, client identifiers/names and the reference; `make openapi` derives the matching enums. `make check-harness-catalog` verifies freshness in the full gate. Native configuration rules stay in their adapter declarations; Core qualification and Runtime availability stay separate. + +- `make sqlc-generate` owns only `services/agents-api/internal/db/sqlc` (sqlc v1.29.0). Do not rewrite landed migrations. +- The public protocol schema is `contracts/agents-api/openapi.yaml`. Preserve its pinned types, coverage ledgers and official SDK/raw HTTP tests when changing API behavior. Core changes keep the independent build and official-client workflow. +- `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-agents-api`. ### Live acceptance -Native adapter changes require their build/check targets and live provider -acceptance. Real execution checks need real models; omitted prerequisites or -mocked responses do not count as live acceptance. Historical remote native -probes are not current validation entry points. +Native adapter changes require their build/check targets and live provider acceptance. Real execution checks need real models; omitted prerequisites or mocked responses do not count as live acceptance. Historical remote native probes are not current validation entry points. ## OpenAgentCore Runtime names @@ -263,57 +150,29 @@ probes are not current validation entry points. | Provider ownership labels | `io.oac.*` | | E2B metadata | `oac_*` | -Provider bootstrap, Runtime images and Harness adapters must agree on these -names. Daemon startup rejects renamed settings before any subcommand and -reports replacements without values; the separate Parsar product integration -settings remain unchanged. No old label is accepted as a fallback. - -Historical Runtime and project-version upgrades are not supported. Do not ship -retired installer conversion implementations; preserve rejection guards under the -[installer lifecycle contract](deploy/install/README.md#versions-and-the-lock). Preserve -older installations, Runtime files, provider resources and Session history; -install the current release separately. Startup never verifies and rebinds historical -allocations or accepts node deployments without a valid specification. Keep the -original Core responsible for unresolved resources; see the -[operator boundary](services/agents-api/HOSTED-SANDBOX-MANAGER.md#historical-installations). -Use this release's template builder for -new E2B templates. Ordinary current-version database initialization uses the -migration runner. - -The dormant Pi adapter keeps its `parsar` provider slug because the separate -Parsar product pins model selections to that identity. This is a product -boundary exception for the name guard, like the skill-upload integration. +Provider bootstrap, Runtime images and Harness adapters must agree on these names. Daemon startup rejects renamed settings before any subcommand and reports replacements without values; the separate Parsar product integration settings remain unchanged. No old label is accepted as a fallback. + +Historical Runtime and project-version upgrades are not supported. Do not ship retired installer conversion implementations; preserve rejection guards under the [installer lifecycle contract](deploy/install/README.md#versions-and-the-lock). Preserve older installations, Runtime files, provider resources and Session history; install the current release separately. Startup never verifies and rebinds historical allocations or accepts node deployments without a valid specification. Keep the original Core responsible for unresolved resources; see the [operator boundary](services/agents-api/HOSTED-SANDBOX-MANAGER.md#historical-installations). Use this release's template builder for new E2B templates. Ordinary current-version database initialization uses the migration runner. + +The dormant Pi adapter keeps its `parsar` provider slug because the separate Parsar product pins model selections to that identity. This is a product boundary exception for the name guard, like the skill-upload integration. Build the MiniMax companion from this revision's pinned patched native sources. ## Branding -Public project branding uses OpenAgentCore. The canonical vector mark is -`docs/assets/openagentcore-logo.svg`; Core Web, docs and landing-page assets use -the same outline, with transparent margins cropped, theme-aware favicon colors -and dark-surface inversion. The canonical SVG preserves the reference PNG canvas. -The README hero uses the supplied `docs/assets/openagentcore-banner.jpeg`. -The `example/parsar/` workbench retains its own name, logo and favicon. -Historical provenance, external repository URLs, import paths and existing data -identifiers retain their original spelling; do not rename those as display copy. +Public project branding uses OpenAgentCore. The canonical vector mark is `docs/assets/openagentcore-logo.svg`; Core Web, docs and landing-page assets use the same outline, with transparent margins cropped, theme-aware favicon colors and dark-surface inversion. The canonical SVG preserves the reference PNG canvas. The README hero uses the supplied `docs/assets/openagentcore-banner.jpeg`. The `example/parsar/` workbench retains its own name, logo and favicon. Historical provenance, external repository URLs, import paths and existing data identifiers retain their original spelling; do not rename those as display copy. ## OpenAgentCore name guard -`make check-names` scans tracked text for retired branding, settings and -installed command names. Each exception in `scripts/name-allowlist.json` names a -path glob, a regular expression and a reason. +`make check-names` scans tracked text for retired branding, settings and installed command names. Each exception in `scripts/name-allowlist.json` names a path glob, a regular expression and a reason. -- An exception covers only its matched text: an allowed repository import cannot - hide a retired setting elsewhere on the line. +- An exception covers only its matched text: an allowed repository import cannot hide a retired setting elsewhere on the line. - Keep exceptions narrow and explain the preserved contract or historical input. These identities stay unchanged: - Go module and source directory paths, npm and Cargo package identities; - public `AgentCoreError`, upstream contract fields and the separate Parsar product; -- persisted credential encryption domains and native-session resume keys, so - existing data can be decrypted and Sessions can resume. +- persisted credential encryption domains and native-session resume keys, so existing data can be decrypted and Sessions can resume. -Conversion inputs, retirement diagnostics and evidence records must still name -the identifiers they reject. Landed migrations keep their original identifiers; -current examples use the new names. +Conversion inputs, retirement diagnostics and evidence records must still name the identifiers they reject. Landed migrations keep their original identifiers; current examples use the new names. diff --git a/docs/architecture.md b/docs/architecture.md index 7d945be7e..dfc788ef5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,16 +1,10 @@ # Architecture -OpenAgentCore separates control, runtime and execution. Core owns durable state -and the API; the Runtime daemon runs work inside an Environment; the native harness -keeps its own model and tool loop. Each connection between them is a defined -protocol, so any part can be replaced without changing Core orchestration. +OpenAgentCore separates control, runtime and execution. Core owns durable state and the API; the Runtime daemon runs work inside an Environment; the native harness keeps its own model and tool loop. Each connection between them is a defined protocol, so any part can be replaced without changing Core orchestration. -This page is a map. Each section names a component, its boundary and the document -that owns its rules. +This page is a map. Each section names a component, its boundary and the document that owns its rules. -Resource provisioning and task execution meet at the Runtime daemon. Managed -sandboxes and user-owned machines enter through different setup paths, then use -the same preparation and execution protocol. +Resource provisioning and task execution meet at the Runtime daemon. Managed sandboxes and user-owned machines enter through different setup paths, then use the same preparation and execution protocol. ```mermaid flowchart TB @@ -40,44 +34,25 @@ flowchart TB H <-->|"MCP protocol"| MCP["MCP servers"] ``` -Dashed arrows show provisioning and installation. Solid arrows show component -interactions; they do not all imply network calls. Sandbox Provider and Harness -contracts are primarily in-process interfaces. The daemon initiates the -Core-Runtime WebSocket connection and exchanges ordered messages with Core. -MCP servers may be local processes or remote services. +Dashed arrows show provisioning and installation. Solid arrows show component interactions; they do not all imply network calls. Sandbox Provider and Harness contracts are primarily in-process interfaces. The daemon initiates the Core-Runtime WebSocket connection and exchanges ordered messages with Core. MCP servers may be local processes or remote services. -Each Harness adapter declares its supported model protocols. Core and Runtime -validate that declaration; model calls use the Harness's own implementation. See -[model execution](../contracts/agents-api/model-execution.md#saved-defaults-and-precedence). +Each Harness adapter declares its supported model protocols. Core and Runtime validate that declaration; model calls use the Harness's own implementation. See [model execution](../contracts/agents-api/model-execution.md#saved-defaults-and-precedence). ## Two APIs, and a machine channel ![Three namespaces and their credentials](assets/architecture-api-surfaces.png) -Core serves three namespaces: the Agents API (`/v1`) for applications, the Core -API (`/core/v1`) for operators, and a machine API (`/api/v1`) for nodes and Runtime -daemons. Each has its own credential; one used elsewhere gets 401. The -[API index](api/README.md) owns the full matrix of callers, credentials and routes. +Core serves three namespaces: the Agents API (`/v1`) for applications, the Core API (`/core/v1`) for operators, and a machine API (`/api/v1`) for nodes and Runtime daemons. Each has its own credential; one used elsewhere gets 401. The [API index](api/README.md) owns the full matrix of callers, credentials and routes. ## Core -Core is the only owner of durable execution facts: Projects and keys, Agents, -Sessions, Turns, Items, Environments, files and audit records, all in PostgreSQL. -It schedules Turns, handles cancellation and pending interactions, and checks that -a requested harness, Environment and capability combination is supported before -starting work. +Core is the only owner of durable execution facts: Projects and keys, Agents, Sessions, Turns, Items, Environments, files and audit records, all in PostgreSQL. It schedules Turns, handles cancellation and pending interactions, and checks that a requested harness, Environment and capability combination is supported before starting work. -Core does not isolate tools, run a model or talk to a vendor SDK directly. It -selects implementations through interfaces and never branches on a harness, -operating system or provider name. See -[Complexity stays in the adapter](../AGENTS.md#complexity-stays-in-the-adapter) and the -[repository map](development.md#repository-map). +Core does not isolate tools, run a model or talk to a vendor SDK directly. It selects implementations through interfaces and never branches on a harness, operating system or provider name. See [Complexity stays in the adapter](../AGENTS.md#complexity-stays-in-the-adapter) and the [repository map](development.md#repository-map). ## Protocol boundaries -The numbers below match the overview. Each protocol defines behavior, ownership, -errors and completion semantics as well as types or method signatures. Its code -and document are listed in [Protocols at every boundary](../AGENTS.md#protocols-at-every-boundary). +The numbers below match the overview. Each protocol defines behavior, ownership, errors and completion semantics as well as types or method signatures. Its code and document are listed in [Protocols at every boundary](../AGENTS.md#protocols-at-every-boundary). | Boundary | Responsibility | | --- | --- | @@ -87,26 +62,17 @@ and document are listed in [Protocols at every boundary](../AGENTS.md#protocols- | 4. Runtime / Harness | Native configuration, execution, event translation and confirmed cleanup | | Harness / Model Provider | Model inference through a protocol supported by the selected Harness | -The Runtime's startup input crosses the provisioning boundary. After connection, -capability preparation belongs to Runtime; the Provider does not become a second -execution path. +The Runtime's startup input crosses the provisioning boundary. After connection, capability preparation belongs to Runtime; the Provider does not become a second execution path. -Not every combination of Harness, model and Environment works. The supported ones -are recorded in [Harness selection](../contracts/agents-api/harness-selection.md) -and the [coverage record](../contracts/agents-api/README.md). +Not every combination of Harness, model and Environment works. The supported ones are recorded in [Harness selection](../contracts/agents-api/harness-selection.md) and the [coverage record](../contracts/agents-api/README.md). ## A Session, end to end -The application creates a Session through the Agents API. Core freezes its -configuration and establishes the execution location: +The application creates a Session through the Agents API. Core freezes its configuration and establishes the execution location: -- **Core-managed (`openai_hosted`):** the Sandbox Provider creates compute and - bootstraps the daemon. -- **User-managed (`self_hosted`):** an administrator issues an executor credential; - the user starts the daemon on their own machine - ([self-hosted guide](getting-started/self-hosted.md)). -- **No workspace Environment (`none`):** Core uses an existing device connection - with the selected Harness's qualified service profile. +- **Core-managed (`openai_hosted`):** the Sandbox Provider creates compute and bootstraps the daemon. +- **User-managed (`self_hosted`):** an administrator issues an executor credential; the user starts the daemon on their own machine ([self-hosted guide](getting-started/self-hosted.md)). +- **No workspace Environment (`none`):** Core uses an existing device connection with the selected Harness's qualified service profile. For workspace Environments, the common path is: @@ -114,27 +80,14 @@ For workspace Environments, the common path is: 2. Prepare the workspace and capabilities from the Session's frozen configuration. 3. Load the fixed installed capability snapshot and prepare or reuse the Session Executor. 4. Submit an input as a Turn; the native Harness runs its model and tool loop. -5. Return output, tool interactions and receipts to Core, which persists the - execution state for application reads and events. -6. Confirm Turn settlement after completion or cancellation. A healthy Executor - can serve the next Turn without destroying the Environment. - -The `none` profile shares the execution protocol without workspace preparation. -Compute availability, daemon connection, completed capability preparation and -execution readiness are separate states. Sending a request is not proof that -execution started or finished. See the -[Environment contract](../contracts/agents-api/environments.md) for preparation -and the [Core-Runtime protocol](runtime-protocol.md) for ordering, receipts and -failure ownership. +5. Return output, tool interactions and receipts to Core, which persists the execution state for application reads and events. +6. Confirm Turn settlement after completion or cancellation. A healthy Executor can serve the next Turn without destroying the Environment. + +The `none` profile shares the execution protocol without workspace preparation. Compute availability, daemon connection, completed capability preparation and execution readiness are separate states. Sending a request is not proof that execution started or finished. See the [Environment contract](../contracts/agents-api/environments.md) for preparation and the [Core-Runtime protocol](runtime-protocol.md) for ordering, receipts and failure ownership. ## Boundaries to keep in mind -- **Isolation belongs to the outer Environment.** The daemon is not a sandbox - ([Runtime and outer isolation](design-principles.md#runtime-and-outer-isolation)). -- **Execution and compute have separate lifetimes.** Closing an executor does not - release its allocation, destroy its Environment or delete its workspace. - Reclamation is an explicit Sandbox Provider operation. -- **Model keys stay with the compute that owns them.** A self-hosted Session brings - its own model provider ([why](user-guide.md#which-model-provider-a-session-uses)). -- **Core Web is an administrator console.** It calls only `/core/v1` and cannot - start Sessions or send input ([Web architecture](web/architecture.md)). +- **Isolation belongs to the outer Environment.** The daemon is not a sandbox ([Runtime and outer isolation](design-principles.md#runtime-and-outer-isolation)). +- **Execution and compute have separate lifetimes.** Closing an executor does not release its allocation, destroy its Environment or delete its workspace. Reclamation is an explicit Sandbox Provider operation. +- **Model keys stay with the compute that owns them.** A self-hosted Session brings its own model provider ([why](user-guide.md#which-model-provider-a-session-uses)). +- **Core Web is an administrator console.** It calls only `/core/v1` and cannot start Sessions or send input ([Web architecture](web/architecture.md)). From 38a056eb47de2301fbef35e86cddc9482fb2cf67 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 07:23:13 +0000 Subject: [PATCH 4/5] docs: reduce AGENTS.md to principles that link to their owners List one entry point per protocol boundary, point to the extension guides for adapter files, add the public API principle moved from CONTRIBUTING.md, state the storage rule with a compact category list owned in detail by docs/configuration.md, and keep known gaps as categorical examples. Move compatibility evidence rules into Required checks, repoint the ownership links in the contract and service READMEs, and drop allowlist entries for removed CONTRIBUTING.md text. --- AGENTS.md | 112 ++++++++++++++------------------- CONTRIBUTING.md | 34 +++++----- contracts/agents-api/README.md | 2 +- docs/architecture.md | 2 +- scripts/name-allowlist.json | 12 +--- services/agents-api/README.md | 2 +- 6 files changed, 65 insertions(+), 99 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c4f5d23a4..2c473bdb9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,94 +4,72 @@ This file holds the design rules every change follows. [Working in this reposito ## Design principles -OpenAgentCore is protocol-first and modular. Core orchestrates operations that protocols define. Sandbox Providers, Runtimes, Harnesses and model providers are replaceable implementations of those protocols; user-owned machines, E2B, Docker and microsandbox expose the same execution protocol. +OpenAgentCore is protocol-first and modular. Core orchestrates operations that protocols define; Sandbox Providers, Runtimes, Harnesses and model providers are replaceable implementations of those protocols. [Architecture](docs/architecture.md) describes each component's responsibilities. ### Protocols at every boundary -- Each boundary between components has exactly one protocol: one code file (interface, wire types and validators) and one document. Change the code and the document together, and update every implementation in the same change. -- Protocols are deterministic. Declare each operation explicitly and type each outcome. Declare support; never discover it through optional-interface type assertions, name checks or implicit fallbacks. An unsupported operation returns an explicit typed error. -- A component joins the system only by implementing a protocol. It gets no private entry point, side channel or path selected by its name. +- Each boundary between components has exactly one protocol: one code file (interface, wire types and validators) and one document. A protocol change edits both and every implementation in one change, reviewed on its own. +- Protocols are deterministic. Every operation is declared and every outcome is typed. Implementations declare what they support, and callers validate each selected combination against those declarations; they never discover support through type assertions, name checks or implicit fallbacks. An unsupported operation or combination returns a typed error. Core never substitutes another implementation, and a capability means the same for every implementation. +- A component joins the system only by implementing a protocol, never through a private entry point, side channel or path selected by its name. | Boundary | Protocol code | Protocol doc | | --- | --- | --- | -| Application–Core (`/v1`) | `contracts/agents-api/openapi.yaml`, generated from `contracts/agents-api/v1/*.go` | [Agents API guide](docs/api/public-agent-api.md) | -| Web and operators–Core (`/core/v1`) | `contracts/agents-api/core.openapi.yaml`, generated from `contracts/agents-api/v1/*.go` | [Web management API](docs/api/web-management.md) | -| Nodes and daemons–Core (`/api/v1`) | `contracts/agents-api/runtime.openapi.yaml`, generated from `contracts/agents-api/v1/*.go` | [Machine connection API](docs/api/README.md#machine-connection-api) | -| Core–Sandbox Provider | `sandbox_provider.go`, `suspension.go`, `selection.go` and `operations.go` in `services/agents-api/internal/sandbox/`; `services/agents-api/internal/providercontract/operations.go`; `services/agents-api/internal/runtimeobs/source.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | -| Core–sandbox node | `wire.go`, `generation_wire.go`, `generation_json.go` and `operations.go` in `services/agents-api/internal/sandbox/node/` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | +| Application–Core (`/v1`) | `contracts/agents-api/openapi.yaml` (generated by `make openapi`) | [Agents API guide](docs/api/public-agent-api.md) | +| Web and operators–Core (`/core/v1`) | `contracts/agents-api/core.openapi.yaml` (generated by `make openapi`) | [Web management API](docs/api/web-management.md) | +| Nodes and daemons–Core (`/api/v1`) | `contracts/agents-api/runtime.openapi.yaml` (generated by `make openapi`) | [Machine connection API](docs/api/README.md#machine-connection-api) | +| Core–Sandbox Provider | `services/agents-api/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | +| Core–sandbox node | `services/agents-api/internal/sandbox/node/wire.go` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | | Provider–Runtime startup | `internal/runtimebootstrap/bootstrap.go` | [Runtime bootstrap](docs/runtime-bootstrap.md) | -| Core–Runtime wire | `internal/agentdaemon/proto/*.go` | [Core–Runtime protocol](docs/runtime-protocol.md) | -| Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go`, with result types and errors in `apps/parsar-daemon/internal/agent/*.go`; `internal/harnessconfig/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | -| Harness–Model provider | `internal/modelprovider/config.go`, `internal/harnessconfig/provider.go` | [Model execution](contracts/agents-api/model-execution.md) | +| Core–Runtime wire | `internal/agentdaemon/proto/` | [Core–Runtime protocol](docs/runtime-protocol.md) | +| Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | +| Harness–Model provider | `internal/modelprovider/config.go` | [Model execution](contracts/agents-api/model-execution.md) | -`make openapi` generates the three OpenAPI files from the Go types and the handler annotations in `services/agents-api/`; never edit them by hand. Rows that list more than one file, a glob or a directory do not meet the single-file rule yet; do not add files to them. +Most boundaries still span several files; the listed file or directory is the entry point. Do not add files to a boundary; consolidate when you change it. ### Complexity stays in the adapter -New complexity lives in the adapter that needs it and never spreads outward. A new implementation adds or changes only these files. Directory names differ per Harness: Claude uses `claude_sdk`, `claudesdk` and `claude`. +- New complexity lives in the adapter that needs it and never spreads outward. A new Sandbox Provider, Harness, model provider or vendor feature changes only its adapter. It adds no Core execution path, store table or column, migration, deployment or configuration field, API field or Web UI specific to one vendor or Harness. +- The [Sandbox Provider guide](docs/sandbox-provider.md) and [Harness onboarding](contracts/agents-api/harness-onboarding.md) list the files an adapter touches today. Any step there that edits shared code is a known gap, not a pattern. +- When the protocol cannot express what an adapter needs, change the protocol. Never add an optional side interface for one implementation. +- Example: implementing the complete declared `CheckpointProvider` lifecycle in one vendor's Provider is an adapter change. A vendor-only pause interface, a Core path for that vendor, vendor receipts in the store or a vendor idle setting in the deployment is not. +- Fix shared lifecycle, admission, cancellation, reuse and performance problems in the common flow, never in branches selected by a Harness, Runtime or vendor name. Core preparation and execution never branch on operating system or Environment source; platform support requires native CI builds and automated tests. +- Each Harness runs its own model and tool loop through a maintained upstream SDK or native protocol, in the Environment's declared workspace directory; its native history or configuration directory is never the workspace. Never build a second executor, a hand-written model/tool loop or a general-purpose compatibility framework to fabricate parity. The public API and persistence never depend on one engine's native item types. +- Each rule has one authored definition. Generate cross-language projections from it or check them against shared fixtures. -- **Sandbox Provider:** its package `services/agents-api/internal/sandbox//`, its construction in `services/agents-api/internal/sandbox/providers/.go` and its entry in `services/agents-api/internal/sandbox/providers/registry.go`; when present, its helper in `services/agents-api/tools/-provider/` and its operator material in `services/agents-api/deploy//`. -- **Harness:** its adapter in `apps/parsar-daemon/internal/agent//`, its native configuration in `internal/harnessconfig//`, its entry in `internal/harnessconfig/builtin/catalog.json`, its discovery and registration in `apps/parsar-daemon/internal/cli/` (`agent_discovery.go`, `agent_registration.go` and `native_harness.go`, plus per-Harness files such as `claude_sdk.go`), its Runtime image in `services/agents-api/deploy//` and, when present, its native package (`packages/claude-sdk-adapter/`, `packages/mcode-harness/`). -- **Model provider:** nothing while it speaks a model protocol that `internal/modelprovider` defines and a Harness declares; a new model protocol is a protocol change. +### Public API -Rules for every adapter: +- The target is the complete OpenAI Agents API (`openai/openai-python` `beta/agents`) as pinned in [`contracts/agents-api/upstream.json`](contracts/agents-api/upstream.json): paths, methods, headers, field presence, nullability, discriminators, defaults, status transitions, pagination, errors and streaming. Engine limitations are gaps to close, never grounds to narrow or redefine the contract. Operations or fields newer than the pinned baseline wait for a protocol upgrade. +- Native differences between Harnesses stay explicit. Record each difference and any unspecified or unverified behavior in the [coverage ledger](contracts/agents-api/README.md), reject explicit enablement of an unsupported feature and never invent official semantics. When a material difference has no clear mapping, stop and ask before changing its semantics. Native differences never relax authentication, isolation, credential protection or data consistency. +- Core owns execution resources: saved Agents, Sessions, Turns, configuration snapshots, Environments, Vaults, usage, pending interactions and events. Applications, including the Parsar product, own users, workspaces, business authorization, Teams and product conversations. They reach Core only through the public contract, with no privileged endpoint or shared tables, and Core never interprets their product payloads. -- A new Sandbox Provider, Harness, model provider or vendor feature adds no Core execution path, store table or column, migration, deployment or configuration field, API field or Web UI specific to that vendor or Harness. -- When the protocol cannot express what an adapter needs, change the protocol as a change of its own: edit its code and document, update every implementation, and have it reviewed on its own. Never add an optional side interface for one implementation. -- Example: a vendor that can pause idle compute implements the declared `Suspend` and `Resume` operations of `CheckpointProvider` in its own Provider; that is an adapter change. A vendor-only pause interface, a Core path for that vendor, vendor receipts in the store or a vendor idle setting in the deployment is not. -- Each Harness runs its own native model and tool loop through a maintained upstream SDK or native protocol. Never build a second executor, a hand-written model/tool loop or a general-purpose compatibility framework to fabricate parity. The public API and persistence never depend on one engine's native item types. +### One home for each setting and datum -Each component owns one part of execution: +- Each setting and each piece of data is written in one place and read from that place, with no second copy, no environment-variable or file fallback and no alias. +- Configuration files are grouped by category, never scattered. A new setting joins its category and lives beside its peers. -| Component | Owns | +| Category | Home | | --- | --- | -| Core | Durable Session, Turn, Environment and allocation state; admission, placement and scheduling | -| Sandbox Provider | Compute creation, bootstrap, renewal and reclamation | -| Runtime | Preparation, execution and recovery inside the Environment | -| Harness adapter | Translation of the common execution contract into native operations | - -- Executor and compute lifetimes are separate; see [Executor and Turn lifetimes](docs/runtime-protocol.md#executor-and-turn-lifetimes). Capability preparation follows [Environments](contracts/agents-api/environments.md#runtime-capability-preparation), and isolation belongs to the outer Environment; see [Runtime and outer isolation](docs/design-principles.md#runtime-and-outer-isolation). -- Fix shared lifecycle, admission, cancellation, reuse and performance problems in the common flow, never in branches selected by a Harness, Runtime or vendor name. -- Express compatibility through declared capabilities and validate each selected combination explicitly. Reject an unsupported combination with an explicit error. Never substitute another implementation or give a capability a different meaning per vendor. -- Core preparation and execution never branch on operating system or Environment source. Platform support requires native CI builds and automated tests; cross-compilation alone is insufficient. -- Each rule has one authored definition. Generate cross-language projections from it or check them against shared fixtures. +| Process settings | `/config.json` | +| Derived process files | `/generated/` | +| Secrets | `/secrets/` | +| Runtime settings and execution data | Core's PostgreSQL | +| Host-local component state | One directory per component under `~/.oac/`, such as `~/.oac/nodes/` and `~/.oac/daemon/` | -### One home for each setting and datum - -- Write each setting and each piece of data in one place and read it from that place. Keep no second copy, no environment-variable or file fallback and no alias. -- Keep configuration files together. Where that is impossible, group them by category. Never scatter them. -- A new setting joins one of the categories below and lives beside its peers. [Configuration](docs/configuration.md) documents the settings themselves. - -| Category | Home | Written by | -| --- | --- | --- | -| Process settings | `/config.json`; the installer defaults `` to `~/.oac/core` | The operator, Web domain setup or `oac domain`; `oac apply` applies them | -| Derived process files | `/generated/` | `oac apply` only | -| Secrets and installation identity | `/secrets/`, one file per secret; `/state.json` | The installer and `oac` commands | -| Provider helper state | `/state/` | Core's provider helpers | -| Managed HTTPS | `/ingress/`: domain status, certificates and control sockets | `oac` and the managed ingress | -| Installed release files | `/oac`, `/native/`, `/node-payload/`; verified bundles in `~/.oac/releases/` | The installer | -| Runtime settings and execution data | Core's PostgreSQL | Web or `/core/v1` for settings; Core, through its APIs, for execution data | -| Node identity, configuration and storage | `~/.oac/nodes//` and microsandbox storage in `~/.oac/m//`, in the node account's home | The node installer and node | -| Daemon settings | `OAC_RUNTIME_*` in the daemon's process environment | The Runtime image, the Sandbox Provider at launch, or `oac-daemon start` from `daemon/installation.json` on a self-hosted machine | -| Runtime state | `~/.oac/daemon/` (Environment binding, installation, executor credential, sessions, scratch and capability installations; connection state per profile in `daemon//`) and adapter state in `~/.oac/runtime//` | The daemon and its adapters | -| Self-hosted executors | `~/.oac/environments//`, each its own Runtime home | The native installer and daemon | -| Build output and caches | `~/.oac/build/`; CI caches in `~/.oac/cache/` | `make` targets; CI | -| Test artifacts | Under `~/.oac/` | Tests and acceptance runs | - -`OAC_RUNTIME_HOME` replaces `~/.oac` for Runtime state and self-hosted executors; `OAC_DEV_HOME` replaces it for build output. +[Configuration](docs/configuration.md) owns the installation layout and the settings themselves. ### Pre-release: no compatibility layers -OpenAgentCore is pre-release. Replace superseded interfaces, execution paths, files and documents outright. Keep no version fallback, compatibility shim, alias or migration for retired behavior unless an explicit upgrade contract requires it. Keep the pinned official public protocol, valid data and still-used, verified infrastructure; do not rewrite working infrastructure only to rename it. +OpenAgentCore is pre-release. Replace superseded interfaces, execution paths and files outright. Keep no version fallback, compatibility shim or migration for superseded behavior unless an explicit upgrade contract requires it. Keep the pinned official public protocol, valid data and still-used, verified infrastructure; do not rewrite working infrastructure only to rename it. ### Known gaps -Existing code that breaks these rules is a gap, not a precedent. Do not copy these patterns; a change that touches one of them moves it toward the rule. +Existing code still breaks these rules in places. The bullets below are examples, not a complete list. Do not copy these patterns. Until a gap is closed, follow the extension guide; a change that touches a gap moves it toward the rule. -- Multi-file protocols: every row of the boundary table that lists more than one file, a glob or a directory. -- Harness support by type assertion: `apps/parsar-daemon/internal/dispatch/workspace_read.go` selects workspace file reads and directory listings by asserting `WorkspaceReader` and `WorkspaceDirectoryLister` instead of reading a declaration; `dispatch/steering.go` reports a declared but missing `Steerer` as unsupported. -- Per-Harness profiles inside Core: `services/agents-api/internal/engine/.go` (`claude.go`, `codex.go`, `mcode.go`). -- Vendor configuration outside the adapter: `sandbox.Selection` has an `E2B` field (`services/agents-api/internal/sandbox/selection.go`) with matching store columns, API fields and operator-client types, as [Register the provider kind](docs/sandbox-provider.md#register-the-provider-kind) directs for new Provider fields. +- Protocol definitions spread over several files, such as the Sandbox Provider contract across `services/agents-api/internal/sandbox/` and `services/agents-api/internal/providercontract/`. +- Support discovered by type assertion, such as daemon workspace reads in `apps/parsar-daemon/internal/dispatch/workspace_read.go` and Core's observation source selection in `services/agents-api/cmd/server/main.go`. +- Harness-specific code in shared places, such as Core engine profiles in `services/agents-api/internal/engine/.go`, daemon discovery and registration, the installer's Harness list and default in `deploy/install/config.schema.json`, and Core's own default Harness when `OAC_DEFAULT_HARNESS` is unset. +- Vendor-specific configuration, routes and UI outside the adapter, such as the E2B selection and store fields (`services/agents-api/internal/sandbox/selection.go`), the `/core/v1/sandbox/e2b/*` routes, E2B credential hooks in `providers.Adapter` and the E2B Web views. +- Persistence and vendor types in the Core and machine OpenAPI documents, such as the `store.*` and `e2b.*` definitions in `contracts/agents-api/core.openapi.yaml`. ## Documentation @@ -101,12 +79,14 @@ Existing code that breaks these rules is a gap, not a precedent. Do not copy the - Write plainly and helpfully. State what the system does and what the reader does. Leave out filler, hedging, defensive negations, process history (PR or design numbers, "retired", "former", "this candidate") and task chronology. - Delete obsolete, historical and duplicate documentation outright. Qualification evidence stays only while it qualifies current behavior. - Do not hard-wrap prose. Write each paragraph, list item and blockquote on one line; editors wrap it for display. +- User-facing documentation uses Web's exact page and action names. +- Application examples read the endpoint and key from `OPENAI_BASE_URL` and `OPENAI_API_KEY`. - Write documentation and code comments in English. The root README also has a Chinese version; user-facing product copy may be bilingual. -- Markdown in `docs/`, component guides and `contracts/` is the authored source. Generated copies, such as the `apps/docs` content and generated references, are never edited by hand: change the source and regenerate. -- Update the owning document in the same branch as the rule, boundary, workflow or generated contract it describes. +- Markdown in `docs/`, component guides and `contracts/` is the authored source. Generated files, such as the OpenAPI documents and the [Harness catalog reference](contracts/agents-api/harness-catalog.md), are never edited by hand: change the source and regenerate. +- Update the owning document in the same branch as the rule, workflow or generated contract it describes. ## Working in this repository -- [CONTRIBUTING.md](CONTRIBUTING.md): workflow, independent review, required checks and naming. +- [CONTRIBUTING.md](CONTRIBUTING.md): read before changing code. Workflow, independent review, required checks and naming. - [Develop OpenAgentCore](docs/development.md): setup, the repository map, focused checks and [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). - [API index](docs/api/README.md): each route's caller and credential. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a7962c52..d35b79101 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,15 @@ # Contributing to OpenAgentCore -Start with [Develop OpenAgentCore](docs/development.md) for checkout, toolchains, the repository map and focused checks. [AGENTS.md](AGENTS.md) owns the design principles and documentation rules. 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. +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 | Subject | Canonical source | | --- | --- | -| Design principles, storage layout and documentation rules | [AGENTS.md](AGENTS.md) | +| Design principles, including public API fidelity and the storage rule, and documentation rules | [AGENTS.md](AGENTS.md) | | Protocol boundaries: each boundary's protocol code and document | [AGENTS.md](AGENTS.md#protocols-at-every-boundary) | | User concepts and authority | [Concepts and ownership](docs/design-principles.md) | -| Architecture overview and diagrams (a map that links to the owners below) | [Architecture](docs/architecture.md) | +| Architecture overview, component responsibilities and diagrams | [Architecture](docs/architecture.md) | | Developer setup, repository map and focused checks | [Develop OpenAgentCore](docs/development.md) | | API callers, credentials and route inventory | [API index](docs/api/README.md) | | Public wire types and qualified behavior | [Agents API contracts](contracts/agents-api/README.md), [pinned upstream](contracts/agents-api/upstream.json), and linked operation contracts | @@ -26,7 +24,7 @@ Every other subject has one canonical owner, listed below. | Claude private bridge and Runtime artifact | [Claude SDK adapter](packages/claude-sdk-adapter/README.md) | | MiniMax Code and Claude Runtime adapter rules | [MiniMax Code Runtime](services/agents-api/deploy/mcode/README.md), [Claude Runtime](services/agents-api/deploy/claude/README.md) | | CI, distribution builds, installer lifecycle and managed HTTPS, release publication | [Maintainer guide](docs/maintainers.md) | -| Operator installation and configuration | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md), [configuration](docs/configuration.md), [operations](docs/getting-started/operations.md) | +| Operator installation, installation layout and configuration | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md), [configuration](docs/configuration.md), [operations](docs/getting-started/operations.md) | | Core Web console server and sign-in | [Web README](apps/web/README.md) | | Web components, interaction and visual rules | [Web design](apps/web/DESIGN.md) and [Web architecture](docs/web/architecture.md) | | Documentation website generation | [Docs app](apps/docs/README.md) | @@ -43,19 +41,8 @@ Preserve copied Runtime and protocol behavior. Existing Go import paths stay unc Agents API is the primary infrastructure deliverable. Parsar is an ordinary client and example application; its feature backlog must not dictate the execution service's public protocol or internal model. Agents API must build, deploy and run without the Parsar product service, frontend or database. An optional Compose deployment may install both services with one PostgreSQL instance, but separate databases, credentials and migrations. The product uses Core exclusively; it has no native daemon or HTTP Agent fallback. -#### Design and compatibility requirements - -- The complete pinned `openai/openai-python` `beta/agents` protocol is the target, including its referenced resources and types. Match paths, methods, headers, field presence, nullability, discriminators, defaults, status transitions, pagination, errors and streaming behavior. Engine limitations are implementation gaps to solve, not grounds for narrowing or redefining the upstream contract. -- Preserve qualified native capability differences across harnesses. If a material difference from the official API has no clear mapping, pause that part and ask the user before changing its semantics. Explicit unsupported enablement rejects; ordinary requests retain native behavior with any official default discrepancy recorded in the coverage ledger. In particular, native programmatic tool calling is not currently qualified as the official default-on behavior. This does not relax authentication, isolation, credential protection or data consistency. -- Pin upstream source and SDK versions in `contracts/agents-api/upstream.json`. Use official SDKs for clients and reuse upstream types or schemas where suitable. SDK deserialization alone is not server validation or proof of compatibility: test raw HTTP payloads and observable workflows as well. Synthetic data and mock model responses may support controlled tests; live execution acceptance must call a real model API through the service, daemon and harness. A real daemon with a synthetic model does not constitute live model validation. Keep provider credentials in private test configuration, outside source, logs and task records. Record unspecified or unverified behavior explicitly; never invent official semantics. When current documentation adds operations or fields absent from the fixed baseline, queue a protocol upgrade instead of silently implementing a new version. Owned-resource live probes can qualify status codes and wire details left unspecified by the SDK; retain request evidence and distinguish observations from guaranteed or fully covered behavior. Track partial coverage in `contracts/agents-api/README.md` until the complete target is verified. Reconcile current coverage summaries with merged routes and recorded acceptance; distinguish accepted profiles, partial implementation, missing operations and unverified semantics. Handler counts are not compatibility percentages, and an active provider probe is not deployment qualification. -- Qualify public workflows through the common Runtime contract and Harness adapter; direct native probes establish feasibility only. -- Native workspace execution must use the declared Environment directory; a separate native history/configuration directory is not a workspace. The public API and persistence/application core must not interpret Parsar product payloads. -- Verify an independent official-client workflow before a Parsar integration. Parsar uses the same public contract as any other client, with no privileged endpoint or direct execution-table access. An OpenAI endpoint is a possible client target only where the requested capabilities and credentials support it. - -- Parsar owns users, workspaces, business authorization, Agent/Team definitions, capabilities, product conversations, IM/sharing, approval decisions and billing. -- Agents API owns protocol saved Agents, execution sessions/turns, effective configuration snapshots, dispatch/cancel, environments, vaults, raw usage, pending interactions, protocol subagents and durable events. Protocol saved Agents/vaults are execution resources, not Parsar marketplace or business roles. Neither service reads the other's tables. Parsar uses a versioned client contract. - A product conversation may map to several execution sessions. An execution session is distinct from a live daemon socket, process or sandbox. Native engine session identifiers belong to the execution service. -- Establish single-Agent execution, approval, cancellation, idempotent submission, persisted recovery queries before Team orchestration. The upstream SSE stream is live-only; recover through Session/Turn/Items reads. Any additional product cursor replay must be documented as an extension, not upstream semantics. Team definitions, management and orchestration belong to Parsar. Agents API establishes single-Agent execution first; business Team loops are deferred. This does not exclude upstream `multi_agent` configuration or subagent resources from protocol coverage. Future business Team orchestration directly depends on `openai/openai-agents-python` in Parsar. +- Establish single-Agent execution, approval, cancellation, idempotent submission, persisted recovery queries before Team orchestration. The upstream SSE stream is live-only; recover through Session/Turn/Items reads. Any additional product cursor replay must be documented as an extension, not upstream semantics. Agents API establishes single-Agent execution first; business Team loops are deferred. This does not exclude upstream `multi_agent` configuration or subagent resources from protocol coverage. Future business Team orchestration directly depends on `openai/openai-agents-python` in Parsar. - Daemon Skill/SP authoring remains a product operation: forward through a scoped product callback with the original requester and workspace checks. A runtime credential alone must not grant business write permissions. ### Optional application example @@ -132,9 +119,18 @@ The role needs `CREATE DATABASE`: managed-provider tests create and drop isolate - `internal/harnessconfig/builtin/catalog.json` is the single authored public Harness registration list. `make generate-harness-catalog` generates Go configuration/profile registration, client identifiers/names and the reference; `make openapi` derives the matching enums. `make check-harness-catalog` verifies freshness in the full gate. Native configuration rules stay in their adapter declarations; Core qualification and Runtime availability stay separate. - `make sqlc-generate` owns only `services/agents-api/internal/db/sqlc` (sqlc v1.29.0). Do not rewrite landed migrations. -- The public protocol schema is `contracts/agents-api/openapi.yaml`. Preserve its pinned types, coverage ledgers and official SDK/raw HTTP tests when changing API behavior. Core changes keep the independent build and official-client workflow. - `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-agents-api`. +### Compatibility evidence + +- Use official SDKs for clients and reuse upstream types or schemas where suitable. SDK deserialization alone is not server validation or proof of compatibility: test raw HTTP payloads and observable workflows as well. +- When changing API behavior, preserve the pinned types, coverage ledgers and official SDK and raw HTTP tests. Core changes keep the independent build and official-client workflow. +- Verify an independent official-client workflow before a Parsar integration. An OpenAI endpoint is a possible client target only where the requested capabilities and credentials support it. +- Qualify public workflows through the common Runtime contract and Harness adapter; direct native probes establish feasibility only. +- Synthetic data and mock model responses may support controlled tests; live execution acceptance must call a real model API through the service, daemon and harness. A real daemon with a synthetic model does not constitute live model validation. Keep provider credentials in private test configuration, outside source, logs and task records. +- Owned-resource live probes can qualify status codes and wire details left unspecified by the SDK; retain request evidence and distinguish observations from guaranteed or fully covered behavior. +- Track partial coverage in `contracts/agents-api/README.md` until the complete target is verified. Reconcile current coverage summaries with merged routes and recorded acceptance; distinguish accepted profiles, partial implementation, missing operations and unverified semantics. Handler counts are not compatibility percentages, and an active provider probe is not deployment qualification. + ### Live acceptance Native adapter changes require their build/check targets and live provider acceptance. Real execution checks need real models; omitted prerequisites or mocked responses do not count as live acceptance. Historical remote native probes are not current validation entry points. diff --git a/contracts/agents-api/README.md b/contracts/agents-api/README.md index 457b8c267..62d8cad23 100644 --- a/contracts/agents-api/README.md +++ b/contracts/agents-api/README.md @@ -23,7 +23,7 @@ Parsar owns product Agents and Teams. This service owns upstream execution resources, including reusable Agents and protocol subagents. The OpenAI Agents Python **SDK** is a separate future dependency for business Team orchestration in Parsar, not the HTTP contract. Design rules live in -[CONTRIBUTING.md](../../CONTRIBUTING.md#design-and-compatibility-requirements). +[AGENTS.md](../../AGENTS.md#public-api). The [resource selector and error qualification](resource-selector-semantics.md) records nullable Skill references and source Files not-found parameter fields, diff --git a/docs/architecture.md b/docs/architecture.md index dfc788ef5..fdc5a1f2c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -48,7 +48,7 @@ Core serves three namespaces: the Agents API (`/v1`) for applications, the Core Core is the only owner of durable execution facts: Projects and keys, Agents, Sessions, Turns, Items, Environments, files and audit records, all in PostgreSQL. It schedules Turns, handles cancellation and pending interactions, and checks that a requested harness, Environment and capability combination is supported before starting work. -Core does not isolate tools, run a model or talk to a vendor SDK directly. It selects implementations through interfaces and never branches on a harness, operating system or provider name. See [Complexity stays in the adapter](../AGENTS.md#complexity-stays-in-the-adapter) and the [repository map](development.md#repository-map). +Core does not isolate tools, run a model or talk to a vendor SDK directly; it reaches Sandbox Providers, Runtimes and Harnesses through the protocols below. The [repository map](development.md#repository-map) shows where each component lives. ## Protocol boundaries diff --git a/scripts/name-allowlist.json b/scripts/name-allowlist.json index 2e3688572..1ac129c78 100644 --- a/scripts/name-allowlist.json +++ b/scripts/name-allowlist.json @@ -526,14 +526,9 @@ }, { "path": "CONTRIBUTING.md", - "regex": "copied from Parsar at|in Parsar\\.|apps/parsar/|Parsar is an ordinary client|Parsar integration|Parsar uses|Parsar owns|Parsar marketplace|belong to Parsar|Parsar retains|Parsar Agents|`parsar` provider slug", + "regex": "copied from Parsar at|in Parsar\\.|apps/parsar/|Parsar is an ordinary client|Parsar integration|`parsar` provider slug", "reason": "These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." }, - { - "path": "CONTRIBUTING.md", - "regex": "`parsar_hosted`", - "reason": "This explicitly unsupported alternative enum is documented to prevent changing the pinned public value." - }, { "path": "contracts/agents-api/README.md", "regex": "Parsar owns product|Parsar, not the HTTP contract|Parsar cutover|Parsar services|no Parsar dependency", @@ -629,11 +624,6 @@ "regex": "(?:AGENTS_API_|CORE_CONSOLE_|PARSAR_)[A-Z0-9_]*\\*?|X-Parsar-Node-ID", "reason": "These names appear in retirement documentation or instructions for an explicitly pinned historical release; current configuration uses OAC settings." }, - { - "path": "CONTRIBUTING.md", - "regex": "~?/\\.parsar/self-hosted/", - "reason": "Documents refusal of the retained legacy self-hosted installation path, not a new default." - }, { "path": "contracts/agents-api/sandbox-deployment.md", "regex": "parsar-core-runtime@", diff --git a/services/agents-api/README.md b/services/agents-api/README.md index 255db7c30..14bc92f13 100644 --- a/services/agents-api/README.md +++ b/services/agents-api/README.md @@ -336,7 +336,7 @@ connections alone do not start a Turn. Submit text, cancellation or function res through the official Session events endpoint; the worker assigns a same-tenant host and preserves that binding. Managed Docker has three-harness evidence. This generic device provisioning path is for `none`; self-hosted Sessions require the dedicated enrollment below. -User-managed enrollment has a separate [qualification record](../../contracts/agents-api/user-managed-runtime-v1.md); complete protocol semantics remain partial. See the [ownership rules](../../CONTRIBUTING.md#product-and-execution-service-separation). +User-managed enrollment has a separate [qualification record](../../contracts/agents-api/user-managed-runtime-v1.md); complete protocol semantics remain partial. See the [ownership rules](../../AGENTS.md#public-api). ### Enable Claude SDK execution From 2269d69b69d840acb05d38c2df1f67edf2500822 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 07:41:28 +0000 Subject: [PATCH 5/5] docs: apply final review fixes to the design principles Name the authored sources of the three HTTP contracts, link the storage categories to the configuration reference, keep only the application boundary principle in the public API rules, restore the test-artifact and application-ownership lines in CONTRIBUTING.md, correct how Core reaches Harnesses in the architecture overview, and point the concepts guide and contract index to AGENTS.md instead of restating its rules. --- AGENTS.md | 25 +++++++++---------------- CONTRIBUTING.md | 2 ++ apps/docs/content/docs/concepts.mdx | 8 +++----- apps/docs/content/guide-sources.json | 4 ++-- contracts/agents-api/README.md | 11 ++--------- docs/architecture.md | 4 ++-- docs/design-principles.md | 8 +++----- scripts/name-allowlist.json | 2 +- 8 files changed, 24 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2c473bdb9..f357f109b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,12 +11,13 @@ OpenAgentCore is protocol-first and modular. Core orchestrates operations that p - Each boundary between components has exactly one protocol: one code file (interface, wire types and validators) and one document. A protocol change edits both and every implementation in one change, reviewed on its own. - Protocols are deterministic. Every operation is declared and every outcome is typed. Implementations declare what they support, and callers validate each selected combination against those declarations; they never discover support through type assertions, name checks or implicit fallbacks. An unsupported operation or combination returns a typed error. Core never substitutes another implementation, and a capability means the same for every implementation. - A component joins the system only by implementing a protocol, never through a private entry point, side channel or path selected by its name. +- Each rule has one authored definition. Generate cross-language projections from it or check them against shared fixtures. | Boundary | Protocol code | Protocol doc | | --- | --- | --- | -| Application–Core (`/v1`) | `contracts/agents-api/openapi.yaml` (generated by `make openapi`) | [Agents API guide](docs/api/public-agent-api.md) | -| Web and operators–Core (`/core/v1`) | `contracts/agents-api/core.openapi.yaml` (generated by `make openapi`) | [Web management API](docs/api/web-management.md) | -| Nodes and daemons–Core (`/api/v1`) | `contracts/agents-api/runtime.openapi.yaml` (generated by `make openapi`) | [Machine connection API](docs/api/README.md#machine-connection-api) | +| Application–Core (`/v1`) | Types in `contracts/agents-api/v1/` and route annotations in `services/agents-api/internal/api/`; `make openapi` generates `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) | +| Web and operators–Core (`/core/v1`) | Route annotations in `services/agents-api/internal/api/`; `make openapi` generates `contracts/agents-api/core.openapi.yaml` | [Core API](docs/api/README.md#core-api) | +| Nodes and daemons–Core (`/api/v1` HTTP routes; the node and daemon wire protocols are separate rows) | Route annotations in `services/agents-api/internal/api/`; `make openapi` generates `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](docs/api/README.md#machine-connection-api) | | Core–Sandbox Provider | `services/agents-api/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | | Core–sandbox node | `services/agents-api/internal/sandbox/node/wire.go` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | | Provider–Runtime startup | `internal/runtimebootstrap/bootstrap.go` | [Runtime bootstrap](docs/runtime-bootstrap.md) | @@ -24,7 +25,7 @@ OpenAgentCore is protocol-first and modular. Core orchestrates operations that p | Runtime–Harness | `apps/parsar-daemon/internal/agent/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | | Harness–Model provider | `internal/modelprovider/config.go` | [Model execution](contracts/agents-api/model-execution.md) | -Most boundaries still span several files; the listed file or directory is the entry point. Do not add files to a boundary; consolidate when you change it. +Most boundaries still span several files; the listed file or directory is the entry point. Do not add files to a boundary; this is a [known gap](#known-gaps). ### Complexity stays in the adapter @@ -34,28 +35,19 @@ Most boundaries still span several files; the listed file or directory is the en - Example: implementing the complete declared `CheckpointProvider` lifecycle in one vendor's Provider is an adapter change. A vendor-only pause interface, a Core path for that vendor, vendor receipts in the store or a vendor idle setting in the deployment is not. - Fix shared lifecycle, admission, cancellation, reuse and performance problems in the common flow, never in branches selected by a Harness, Runtime or vendor name. Core preparation and execution never branch on operating system or Environment source; platform support requires native CI builds and automated tests. - Each Harness runs its own model and tool loop through a maintained upstream SDK or native protocol, in the Environment's declared workspace directory; its native history or configuration directory is never the workspace. Never build a second executor, a hand-written model/tool loop or a general-purpose compatibility framework to fabricate parity. The public API and persistence never depend on one engine's native item types. -- Each rule has one authored definition. Generate cross-language projections from it or check them against shared fixtures. ### Public API - The target is the complete OpenAI Agents API (`openai/openai-python` `beta/agents`) as pinned in [`contracts/agents-api/upstream.json`](contracts/agents-api/upstream.json): paths, methods, headers, field presence, nullability, discriminators, defaults, status transitions, pagination, errors and streaming. Engine limitations are gaps to close, never grounds to narrow or redefine the contract. Operations or fields newer than the pinned baseline wait for a protocol upgrade. - Native differences between Harnesses stay explicit. Record each difference and any unspecified or unverified behavior in the [coverage ledger](contracts/agents-api/README.md), reject explicit enablement of an unsupported feature and never invent official semantics. When a material difference has no clear mapping, stop and ask before changing its semantics. Native differences never relax authentication, isolation, credential protection or data consistency. -- Core owns execution resources: saved Agents, Sessions, Turns, configuration snapshots, Environments, Vaults, usage, pending interactions and events. Applications, including the Parsar product, own users, workspaces, business authorization, Teams and product conversations. They reach Core only through the public contract, with no privileged endpoint or shared tables, and Core never interprets their product payloads. +- Applications, including the Parsar product, reach Core only through the public contract, with no privileged endpoint and no shared tables, and Core never interprets their product payloads. ### One home for each setting and datum - Each setting and each piece of data is written in one place and read from that place, with no second copy, no environment-variable or file fallback and no alias. - Configuration files are grouped by category, never scattered. A new setting joins its category and lives beside its peers. -| Category | Home | -| --- | --- | -| Process settings | `/config.json` | -| Derived process files | `/generated/` | -| Secrets | `/secrets/` | -| Runtime settings and execution data | Core's PostgreSQL | -| Host-local component state | One directory per component under `~/.oac/`, such as `~/.oac/nodes/` and `~/.oac/daemon/` | - -[Configuration](docs/configuration.md) owns the installation layout and the settings themselves. +The categories are [process settings](docs/configuration.md#process-settings-configjson), [derived files](docs/configuration.md#how-oac-apply-works), [secrets](docs/configuration.md#secrets-and-identity), and Core's database for [runtime settings](docs/configuration.md#runtime-settings-web) and execution data. [Configuration](docs/configuration.md) owns the installation layout and the settings themselves. ### Pre-release: no compatibility layers @@ -69,6 +61,7 @@ Existing code still breaks these rules in places. The bullets below are examples - Support discovered by type assertion, such as daemon workspace reads in `apps/parsar-daemon/internal/dispatch/workspace_read.go` and Core's observation source selection in `services/agents-api/cmd/server/main.go`. - Harness-specific code in shared places, such as Core engine profiles in `services/agents-api/internal/engine/.go`, daemon discovery and registration, the installer's Harness list and default in `deploy/install/config.schema.json`, and Core's own default Harness when `OAC_DEFAULT_HARNESS` is unset. - Vendor-specific configuration, routes and UI outside the adapter, such as the E2B selection and store fields (`services/agents-api/internal/sandbox/selection.go`), the `/core/v1/sandbox/e2b/*` routes, E2B credential hooks in `providers.Adapter` and the E2B Web views. +- Host-local state spread over several `~/.oac/` directories, such as the Runtime's `~/.oac/daemon/`, `~/.oac/runtime//` and `~/.oac/environments//`. - Persistence and vendor types in the Core and machine OpenAPI documents, such as the `store.*` and `e2b.*` definitions in `contracts/agents-api/core.openapi.yaml`. ## Documentation @@ -87,6 +80,6 @@ Existing code still breaks these rules in places. The bullets below are examples ## Working in this repository -- [CONTRIBUTING.md](CONTRIBUTING.md): read before changing code. Workflow, independent review, required checks and naming. +- [CONTRIBUTING.md](CONTRIBUTING.md): read before changing code. Documentation ownership, repository boundary, workflow, independent review, required checks and naming. - [Develop OpenAgentCore](docs/development.md): setup, the repository map, focused checks and [the guide for each extension boundary](docs/development.md#choose-an-extension-boundary). - [API index](docs/api/README.md): each route's caller and credential. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d35b79101..df21e9d58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,7 @@ Preserve copied Runtime and protocol behavior. Existing Go import paths stay unc Agents API is the primary infrastructure deliverable. Parsar is an ordinary client and example application; its feature backlog must not dictate the execution service's public protocol or internal model. Agents API must build, deploy and run without the Parsar product service, frontend or database. An optional Compose deployment may install both services with one PostgreSQL instance, but separate databases, credentials and migrations. The product uses Core exclusively; it has no native daemon or HTTP Agent fallback. +- Parsar owns users, workspaces, business authorization, Agent/Team definitions, capabilities, product conversations, IM/sharing, approval decisions and billing. - A product conversation may map to several execution sessions. An execution session is distinct from a live daemon socket, process or sandbox. Native engine session identifiers belong to the execution service. - Establish single-Agent execution, approval, cancellation, idempotent submission, persisted recovery queries before Team orchestration. The upstream SSE stream is live-only; recover through Session/Turn/Items reads. Any additional product cursor replay must be documented as an extension, not upstream semantics. Agents API establishes single-Agent execution first; business Team loops are deferred. This does not exclude upstream `multi_agent` configuration or subagent resources from protocol coverage. Future business Team orchestration directly depends on `openai/openai-agents-python` in Parsar. - Daemon Skill/SP authoring remains a product operation: forward through a scoped product callback with the original requester and workspace checks. A runtime credential alone must not grant business write permissions. @@ -76,6 +77,7 @@ Record unrelated findings without automatically starting them. Do not claim a br - Split growing files at an existing ownership boundary instead of adding unrelated responsibilities. - 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 the [API index](docs/api/README.md) and link their detailed contract. ### Review diff --git a/apps/docs/content/docs/concepts.mdx b/apps/docs/content/docs/concepts.mdx index 03466d730..8b71558f5 100644 --- a/apps/docs/content/docs/concepts.mdx +++ b/apps/docs/content/docs/concepts.mdx @@ -3,10 +3,8 @@ title: "Concepts and ownership" description: "Projects, credentials and the boundary between applications, administration and execution." --- -OpenAgentCore implements the OpenAI Agents API. Its public contract follows the -repository's pinned upstream baseline. Documented native harness differences stay -explicit; Core extensions never silently change upstream resource shapes or -execution semantics. +OpenAgentCore implements the OpenAI Agents API under the +[public API rules](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/AGENTS.md#public-api). ## Three namespaces, three credentials @@ -86,7 +84,7 @@ not protect Runtime data from tools running as the same user. Do not add product users, RBAC, cross-Project shared assets, administrator execution or compatibility with old private protocols. Implementers follow the -[contributor rules](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/CONTRIBUTING.md) and the +[design rules](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/AGENTS.md#design-principles) and the [Core–Runtime protocol](/runtime-protocol). Native failure classification is adapter-owned and uses finite, structured native diff --git a/apps/docs/content/guide-sources.json b/apps/docs/content/guide-sources.json index 76771d001..c9eac5446 100644 --- a/apps/docs/content/guide-sources.json +++ b/apps/docs/content/guide-sources.json @@ -2,7 +2,7 @@ "revision": "f6d258735fc601c521dd990e6f9e1ed261f4ef2d", "sources": { "docs/getting-started/README.md": "7b7f82e484a20d7847e970c2192709091107b6acc253709c9f38ef91caeabcf1", - "docs/design-principles.md": "21a05fb089804db6fab5674ec9a6cf849a3affedad2ca927a38d9b46eeec9a50", + "docs/design-principles.md": "334e0d477c255552f874f3ca8a2db603d0d07892ad7d58930bf8e3d06b86c636", "docs/web/architecture.md": "cf694aa624cf6078a154c2f8fdd67055d41dea0c0bb80b8dc8f0cdbc5d572fb1", "docs/getting-started/install.md": "84b21002136acd4f006392685b7a071323336e87c1aac6e3c23ca56acb40833c", "docs/getting-started/install-options.md": "e03487bb6d978f84c596467028e25fd99fdc21cf2060af24ceb68df885084798", @@ -32,7 +32,7 @@ }, "outputs": { "content/docs/index.mdx": "bf78e8aab0a834fb62ee7287fef3e29363b7384e63ec61aefcf7448f65a71a80", - "content/docs/concepts.mdx": "88ba65e1ba902921d6cd5da2866620a6dbef52c041db991312a138884fb43a4e", + "content/docs/concepts.mdx": "b9aceda2f72f3f1239e5518c3cecff8c9c0aa11a3eb622ddf9db6af2984a1abc", "content/docs/execution-model.mdx": "7b8d8498a1b157270f00a8c370c9a86547fa481df9ffa8904c810946b1626b38", "content/docs/install.mdx": "6c3ec01d1b80cbce35d58e3f141b0fa832d6294a2ecc07c3b286ecc56ba66919", "content/docs/install-options.mdx": "aaafc209293a905d5b433511149aa1f0cc422bd31d5bb5b6cd7eec0d532ab8eb", diff --git a/contracts/agents-api/README.md b/contracts/agents-api/README.md index 62d8cad23..589ca69e1 100644 --- a/contracts/agents-api/README.md +++ b/contracts/agents-api/README.md @@ -31,15 +31,8 @@ with official observations separated from Core acceptance. ## Implementation direction -Keep the independent service, authentication, PostgreSQL/sqlc persistence, -transactional admission and official-client test harness. Shared Runtime contracts -define execution semantics; native representations stay inside adapters. - -Concentrate native configuration, structured input/output and Item translation -in an execution adapter. The application core owns execution state and persistence; -engine-specific shapes stay at the adapter boundary. Codex uses its native -app-server; Claude uses the maintained Agent SDK. Reuse native protocols and SDKs -for further harnesses rather than adding another model/tool loop. +Adapter and persistence design follows the +[design rules](../../AGENTS.md#complexity-stays-in-the-adapter). The [harness contract and parity baseline](harnesses.md) describes equal-engine registration, qualification and shared acceptance. Verify configuration against actual execution: response defaults must not merely diff --git a/docs/architecture.md b/docs/architecture.md index fdc5a1f2c..c39096673 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -48,7 +48,7 @@ Core serves three namespaces: the Agents API (`/v1`) for applications, the Core Core is the only owner of durable execution facts: Projects and keys, Agents, Sessions, Turns, Items, Environments, files and audit records, all in PostgreSQL. It schedules Turns, handles cancellation and pending interactions, and checks that a requested harness, Environment and capability combination is supported before starting work. -Core does not isolate tools, run a model or talk to a vendor SDK directly; it reaches Sandbox Providers, Runtimes and Harnesses through the protocols below. The [repository map](development.md#repository-map) shows where each component lives. +Core does not isolate tools, run a model or talk to a vendor SDK directly. It reaches Sandbox Providers and Runtimes through the protocols below, and Harnesses only through the Runtime. The [repository map](development.md#repository-map) shows where each component lives. ## Protocol boundaries @@ -62,7 +62,7 @@ The numbers below match the overview. Each protocol defines behavior, ownership, | 4. Runtime / Harness | Native configuration, execution, event translation and confirmed cleanup | | Harness / Model Provider | Model inference through a protocol supported by the selected Harness | -The Runtime's startup input crosses the provisioning boundary. After connection, capability preparation belongs to Runtime; the Provider does not become a second execution path. +The [bootstrap contract](runtime-bootstrap.md) carries the Runtime's startup input across the provisioning boundary. After connection, capability preparation belongs to Runtime; the Provider does not become a second execution path. Not every combination of Harness, model and Environment works. The supported ones are recorded in [Harness selection](../contracts/agents-api/harness-selection.md) and the [coverage record](../contracts/agents-api/README.md). diff --git a/docs/design-principles.md b/docs/design-principles.md index 47b89af23..1452a2753 100644 --- a/docs/design-principles.md +++ b/docs/design-principles.md @@ -1,9 +1,7 @@ # Core design principles -OpenAgentCore implements the OpenAI Agents API. Its public contract follows the -repository's pinned upstream baseline. Documented native harness differences stay -explicit; Core extensions never silently change upstream resource shapes or -execution semantics. +OpenAgentCore implements the OpenAI Agents API under the +[public API rules](../AGENTS.md#public-api). ## Three namespaces, three credentials @@ -83,7 +81,7 @@ not protect Runtime data from tools running as the same user. Do not add product users, RBAC, cross-Project shared assets, administrator execution or compatibility with old private protocols. Implementers follow the -[contributor rules](../CONTRIBUTING.md) and the +[design rules](../AGENTS.md#design-principles) and the [Core–Runtime protocol](runtime-protocol.md). Native failure classification is adapter-owned and uses finite, structured native diff --git a/scripts/name-allowlist.json b/scripts/name-allowlist.json index 1ac129c78..ab1ac6587 100644 --- a/scripts/name-allowlist.json +++ b/scripts/name-allowlist.json @@ -526,7 +526,7 @@ }, { "path": "CONTRIBUTING.md", - "regex": "copied from Parsar at|in Parsar\\.|apps/parsar/|Parsar is an ordinary client|Parsar integration|`parsar` provider slug", + "regex": "copied from Parsar at|in Parsar\\.|apps/parsar/|Parsar is an ordinary client|Parsar integration|Parsar owns|`parsar` provider slug", "reason": "These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." }, {