diff --git a/AGENTS.md b/AGENTS.md index 25c344b6f..f357f109b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,16 +1,85 @@ # 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). -- Run `make sqlc-generate` after query changes and `make openapi` after handler - changes; review and commit the generated contracts with their source changes. -- 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. +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. [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. 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`) | 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) | +| 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) | + +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 + +- 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. + +### 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. +- 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. + +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 + +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 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. + +- 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. +- 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 + +- 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. +- 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 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): 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 258f02624..df21e9d58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,318 +1,97 @@ # 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. - -Every other rule has one canonical owner, listed below. Change that owner, not a -copy, when a contract changes. +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 | | --- | --- | -| 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) | +| 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, 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 | | 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` | | 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` | | 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` | | 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) | | 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) | -### 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 -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. - -#### 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. Do not build - a separate executor or model loop to fabricate parity. 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. Retain historical evidence with 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. - 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 - 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. +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. ### 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. -## 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 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. Historical 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. -- 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. +- 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 -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 @@ -324,9 +103,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. @@ -337,37 +114,28 @@ 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. +- `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. +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 @@ -376,62 +144,33 @@ 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_*` | -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. Landed migrations and historical evidence stay as repository -history; 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 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/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 457b8c267..589ca69e1 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, @@ -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 c01664cfd..c39096673 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,73 +34,45 @@ 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 -[the decoupling principle](../CONTRIBUTING.md#decoupling-principle) 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 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 -The numbers below match the overview. Each contract defines behavior, ownership, -errors and completion semantics as well as types or method signatures. +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 | 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) | +| 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 [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. +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). +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)). 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 8a13d8b23..ab1ac6587 100644 --- a/scripts/name-allowlist.json +++ b/scripts/name-allowlist.json @@ -524,21 +524,11 @@ "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", + "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." }, - { - "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", @@ -634,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