From 62f324c60b09b6c98c5e14db3a73578502e56c17 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:18:34 +0000 Subject: [PATCH 1/7] docs: consolidate concepts and top-level contributor guides --- CONTRIBUTING.md | 108 ++++++++++++-------------- README.md | 8 +- README.zh-CN.md | 8 +- contracts/agents-api/admin-api.md | 2 +- docs/api/README.md | 2 +- docs/architecture.md | 104 +++++++------------------ docs/concepts.md | 33 ++++++++ docs/design-principles.md | 90 --------------------- docs/development.md | 90 ++++----------------- docs/examples.md | 29 +------ docs/getting-started/operations.md | 4 +- docs/getting-started/self-hosted.md | 2 +- docs/sandbox-provider.md | 2 +- docs/web/README.md | 2 +- example/README.md | 8 -- packages/claude-sdk-adapter/README.md | 2 +- 16 files changed, 143 insertions(+), 351 deletions(-) create mode 100644 docs/concepts.md delete mode 100644 docs/design-principles.md delete mode 100644 example/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70167c981..be8f11c40 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,47 +6,51 @@ This guide owns how to work in the repository: documentation ownership, the repo | Subject | Canonical source | | --- | --- | -| 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) | +| Design principles, public API fidelity, settings and data ownership, documentation rules | [AGENTS.md](AGENTS.md) | +| Protocol code and documents at each component boundary | [Protocol map](AGENTS.md#protocols-at-every-boundary) | +| Projects, keys, resource isolation, administrator authority, secrets and audit concepts | [Concepts and ownership](docs/concepts.md) | +| Component responsibilities and Session flow | [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/core/IMPLEMENTATION.md) and [service README](services/core/README.md) | -| Environment ownership and capability preparation (Skills, Plugins, MCP, `packages.system`) | [Environments](contracts/agents-api/environments.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/daemon/internal/agent/mcp_binding.go` | -| Harness qualification and acceptance | [Harness capabilities](contracts/agents-api/harness-capabilities.md) and [Harness onboarding](contracts/agents-api/harness-onboarding.md#qualify-the-adapter) | -| Harness service qualification declarations and registration | [Explicit service qualification](contracts/agents-api/harness-onboarding.md#explicit-service-qualification) and `services/core/internal/engine/profile.go` | -| Harness selection and Agent defaults | [Harness selection](contracts/agents-api/model-execution.md#harness-selection) | -| Provider registration validation | [Sandbox Provider guide](docs/sandbox-provider.md#registration-validation) | -| Provider selection, sandbox deployment and E2B setup | [Sandbox deployment](contracts/agents-api/sandbox-deployment.md) | -| Hosted sandbox nodes | [Nodes guide](docs/getting-started/nodes.md) and [sandbox deployment contract](contracts/agents-api/sandbox-deployment.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/core/deploy/mcode/README.md), [Claude Runtime](services/core/deploy/claude/README.md) | -| CI, distribution builds, installer lifecycle and managed HTTPS, release publication | [Maintainer guide](docs/maintainers.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 | [Console server](docs/web/console-server.md) | -| Web components, interaction and visual rules | [Web design](apps/web/DESIGN.md) and [Web product](apps/web/PRODUCT.md) | -| Documentation website generation | Docs app | +| Public wire semantics and protocol coverage | [Agents API contracts](contracts/agents-api/README.md) | +| Machine connection routes | [Machine connection API](docs/api/README.md#machine-connection-api) | +| Core service setup, tests and generation | [Core service guide](services/core/README.md) | +| Core implementation constraints beyond the public contracts | [Implementation constraints](services/core/IMPLEMENTATION.md) | +| Environment ownership, preparation, Skills, Plugins, packages and MCP bindings | [Environments](contracts/agents-api/environments.md) | +| Built-in Harness identifiers and display names | `internal/harnessconfig/builtin/catalog.json` and its [generated reference](contracts/agents-api/harness-catalog.md) | +| Harness registration, service qualification and acceptance | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | +| Harness capabilities by placement | [Harness capabilities](contracts/agents-api/harness-capabilities.md) | +| Harness selection, model providers and native parameters | [Model execution](contracts/agents-api/model-execution.md) | +| Provider registration and lifecycle | [Sandbox Provider guide](docs/sandbox-provider.md) | +| Sandbox deployment, selection and administrative transitions | [Sandbox deployment](contracts/agents-api/sandbox-deployment.md) | +| Operator node tasks | [Nodes guide](docs/getting-started/nodes.md) | +| Codex, Claude and MiniMax Runtime adapters and images | [Codex](services/core/deploy/codex/README.md), [Claude](services/core/deploy/claude/README.md), [MiniMax](services/core/deploy/mcode/README.md) | +| Claude private SDK bridge | [Claude SDK adapter](packages/claude-sdk-adapter/README.md) | +| E2B template construction | [E2B template builder](services/core/deploy/e2b/README.md) | +| E2B and microsandbox Provider helper implementation | [E2B helper](services/core/tools/e2b-provider/README.md), [microsandbox helper](services/core/tools/microsandbox-provider/README.md) | +| Runtime telemetry responses | [Runtime telemetry API](contracts/agents-api/runtime-observability-api.md) | +| Runtime observation, sampling, retention and export | [Runtime observability](contracts/agents-api/runtime-observability.md) | +| Distribution builds, Runtime image builds, CI and publication | [Maintainer guide](docs/maintainers.md) | +| Installer lifecycle, locking, generated state, managed HTTPS and downloads | [Installer design rules](deploy/install/README.md) | +| Operator installation and alternatives | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md) | +| Settings, defaults, files and installation layout | [Configuration](docs/configuration.md) | +| Operator commands, keys, backup and version policy | [Operations](docs/getting-started/operations.md) | +| Web console request boundary and sign-in | [Console server](docs/web/console-server.md) | +| Web page behavior and visual rules | [Web product](apps/web/PRODUCT.md), [Web design](apps/web/DESIGN.md) | +| Application example behavior and local operation | [Application example](example/parsar/README.md) | ## Repository boundary -This repository is the standalone execution substrate, copied from the Parsar repository. 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. - -Preserve copied Runtime and protocol behavior. Go import paths use this repository's module and do not require fetching the original repository. Do not automatically sync or delete the original repository's Core. +This repository contains the Core API and database, Runtime daemon, Harness and Sandbox Provider adapters, shared protocol packages, Web administrator console and their build and test tools. Product applications stay outside that service boundary. Keep the external Parsar product's `server/`, `apps/parsar/`, CLI, plugins and deployment stack in its own repository; do not automatically sync or delete its Core copy. Go imports resolve through this repository's module. ### Product and execution service separation -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. +Core must build, deploy and run independently of product services, frontends and databases. Applications follow the [public API boundary](AGENTS.md#public-api); their feature backlogs do not define Core's public protocol or storage model. Applications that share a PostgreSQL server with Core must use separate databases, credentials and migrations. -- 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. +- Parsar owns users, workspaces, business authorization, Agent/Team definitions, capabilities, product conversations, IM/sharing, approval decisions and billing. It uses Core for execution. +- A product conversation may reference several execution Sessions. Core owns native engine session identities; an execution Session has its own lifetime, separate from a daemon connection, process or sandbox. +- Build application orchestration on the [public Session and event contract](docs/api/public-agent-api.md). Product cursor replay must be an explicit product extension. Business Team orchestration belongs to the application; Core's pinned `multi_agent` and Subagent resources remain part of the public contract. +- Daemon Skill/SP authoring is a product operation: forward it through a scoped product callback that checks the original requester and workspace. A Runtime credential alone must not authorize business writes. ### Optional application example @@ -70,7 +74,7 @@ When documents conflict, apply the latest explicit user decision and update the 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. Scope compatibility claims to the operations and placements verified. ### Implementation conventions @@ -97,17 +101,7 @@ Toolchain setup and focused commands are in [Develop OpenAgentCore](docs/develop ### Full gate -Run `make check` before completion. It includes: - -- all daemon and shared Go tests, including native daemon filesystem tests; -- Core contract, client and service tests and standalone API builds; -- a real dedicated PostgreSQL test database and byte-for-byte sqlc checks; -- 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. - -It excludes Parsar product Web and server gates. +Run `make check` before completing code changes. The `check` target in the [Makefile](Makefile) is the authoritative list of gates. [Focused validation](docs/development.md#validate-a-change) selects checks for development; [live acceptance](#live-acceptance) qualifies native execution beyond fixtures and builds. ### Test database @@ -127,17 +121,15 @@ The role needs `CREATE DATABASE`: managed-provider tests create and drop isolate ### 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. +Use official SDKs and upstream types or schemas where suitable. Validate raw HTTP payloads and observable workflows alongside SDK behavior. API changes preserve the pinned contracts, coverage ledger, official-client tests and Core's independent build. Verify the official-client workflow before application integration; an OpenAI endpoint is a test target only when the required capabilities and credentials are available. + +Controlled fixtures and synthetic model responses qualify deterministic behavior. Live execution acceptance calls a real model API through Core, the daemon and the Harness adapter. Direct native probes establish feasibility. Keep provider credentials in private test configuration, outside source, logs and task records. + +For wire details unspecified by the pinned SDK, probe resources you own and retain request evidence. Distinguish observed behavior from guarantees, accepted profiles from complete coverage, and provider connectivity from deployment qualification. Maintain those distinctions in the [coverage ledger](contracts/agents-api/README.md). ### 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. Follow [Harness qualification](contracts/agents-api/harness-onboarding.md#qualify-the-adapter) for native model execution. State which checks ran, which used fixtures and which lacked prerequisites. Changes to native package pins require the same qualification; build the MiniMax companion from this revision's pinned patched sources. ## OpenAgentCore Runtime names @@ -152,25 +144,23 @@ Native adapter changes require their build/check targets and live provider accep Provider bootstrap, Runtime images and Harness adapters must agree on these names. The separate Parsar product integration settings keep their own names. -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 [installation version policy](docs/getting-started/operations.md#installation-version-policy). Use this release's template builder for new E2B templates. Ordinary current-version database initialization uses the migration runner. - -Build the MiniMax companion from this revision's pinned patched native sources. +The [installation version policy](docs/getting-started/operations.md#installation-version-policy) owns release changes and preservation of installed data and resources. ## 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 and existing data identifiers retain their original spelling; do not rename those as display copy. +Use OpenAgentCore for public project branding. The canonical mark is `docs/assets/openagentcore-logo.svg`; Web uses its outline with cropped transparent margins, theme-aware favicon colors and dark-surface inversion. The README banner is `docs/assets/openagentcore-banner.jpeg`. The `example/parsar/` workbench keeps its own name, logo and favicon. Preserve external repository URLs and data identifiers when changing 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. - 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. -- The guard also fails on an exception that excuses no retired identifier. Remove an exception together with the last text it covered. +- Keep exceptions narrow and explain the preserved contract or detection input. +- The guard fails on an exception that excuses no retired identifier. Remove an exception together with the last text it covers. These identities stay unchanged: - 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. -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. +Detection inputs name the identifiers they reject. Landed migrations keep their original identifiers; application and operator examples use the current names. diff --git a/README.md b/README.md index 7a6693a7a..c0d7050e9 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/ Then: -1. **Sign in to Web**, the admin console, with the Core key the installer created. +1. **Sign in to Web**, the admin console, with the Core key the installer created, and **configure the domain and HTTPS**. 2. **Set a default model** and **issue a Project API key**. 3. **Add execution capacity:** a node, E2B, or your own machine. 4. **[Run your first Session](docs/getting-started/quickstart.md)** with the OpenAI SDK. @@ -53,14 +53,14 @@ and a quick local trial. Listen addresses, ports and other options: [installatio ![OpenAgentCore architecture](docs/assets/architecture.png) -Core exposes two APIs: +Applications and operators use these Core APIs: | API | Path | Used by | | --- | --- | --- | | **[Agents API](docs/api/public-agent-api.md)** | `/v1` | Your applications. Same protocol as [OpenAI's Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) | | **[Core API](contracts/agents-api/admin-api.md)** | `/core/v1` | Operators, through Web | -Core keeps all state. The Runtime runs the chosen harness inside the Environment. +Core keeps durable execution state. The Runtime runs the chosen harness inside the Environment. Each connection is a defined protocol, so any part can be replaced on its own. See the [architecture guide](docs/architecture.md). @@ -72,7 +72,7 @@ the [architecture guide](docs/architecture.md). | Build an application on the API | [Quickstart](docs/getting-started/quickstart.md), then the [Agents API guide](docs/api/public-agent-api.md) | | See a complete application | [Examples](docs/examples.md) | | Run agents on my own machine | [Self-hosted execution](docs/getting-started/self-hosted.md) | -| Check verified Runtime capabilities and limits | [Harness capabilities](contracts/agents-api/harness-capabilities.md) | +| Check Harness capabilities and limits | [Harness capabilities](contracts/agents-api/harness-capabilities.md) | | Understand the design | [Architecture](docs/architecture.md) | | Add a sandbox, harness or other component | [Developer guide](docs/development.md) | diff --git a/README.zh-CN.md b/README.zh-CN.md index 3a9c867a7..1a6fea695 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -39,7 +39,7 @@ curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/ 然后： -1. 用安装器生成的 Core key **登录 Web**（管理控制台）。 +1. 用安装器生成的 Core key **登录 Web**（管理控制台），并**配置域名和 HTTPS**。 2. **设置默认模型**，并**签发 Project API key**。 3. **添加执行资源**：节点、E2B，或你自己的机器。 4. 用 OpenAI SDK **[运行第一个 Session](docs/getting-started/quickstart.md)**。 @@ -50,14 +50,14 @@ curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/ ![OpenAgentCore 架构](docs/assets/architecture.png) -Core 对外提供两组 API： +应用和管理员使用以下 Core API： | API | 路径 | 调用方 | | --- | --- | --- | | **[Agents API](docs/api/public-agent-api.md)** | `/v1` | 你的应用，与 [OpenAI 的 Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) 协议一致 | | **[Core API](contracts/agents-api/admin-api.md)** | `/core/v1` | 管理员，通过 Web 调用 | -所有状态都由 Core 保存；Runtime 在 Environment 中运行所选 Harness。各部件之间都通过既定协议连接， +持久化执行状态由 Core 保存；Runtime 在 Environment 中运行所选 Harness。各部件之间都通过既定协议连接， 任何一个都可以单独替换。详见[架构说明](docs/architecture.md)。 ## 文档 @@ -68,7 +68,7 @@ Core 对外提供两组 API： | 基于 API 开发应用 | [快速开始](docs/getting-started/quickstart.md)，然后看 [Agents API 指南](docs/api/public-agent-api.md) | | 看一个完整的应用 | [示例](docs/examples.md) | | 在自己的机器上运行 Agent | [自托管执行](docs/getting-started/self-hosted.md) | -| 查看 Runtime 能力和验收范围 | [Harness 能力](contracts/agents-api/harness-capabilities.md) | +| 查看 Harness 能力和限制 | [Harness 能力](contracts/agents-api/harness-capabilities.md) | | 了解设计 | [架构说明](docs/architecture.md) | | 接入新的沙箱、Harness 或其他组件 | [开发指南](docs/development.md) | diff --git a/contracts/agents-api/admin-api.md b/contracts/agents-api/admin-api.md index c9965cdf9..add7e11cc 100644 --- a/contracts/agents-api/admin-api.md +++ b/contracts/agents-api/admin-api.md @@ -39,7 +39,7 @@ Paths are relative to `/core/v1`. ## Projects and keys -A Project owns one execution tenant; its keys share its principal and assets ([Projects own assets](../../docs/design-principles.md#projects-own-assets)). Web's **Projects and keys** page uses these routes. +A Project owns one execution tenant; its keys share its principal and assets ([Projects own assets](../../docs/concepts.md#projects-own-assets)). Web's **Projects and keys** page uses these routes. | Operation | Route | Result | | --- | --- | --- | diff --git a/docs/api/README.md b/docs/api/README.md index 06947eba1..a7ffb3b61 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -8,7 +8,7 @@ Core serves three namespaces. Each has one kind of caller and its own credential | `/core/v1` | Web's console server and operator scripts | [Core key](../getting-started/operations.md#core-key) | Installation facts, Projects and keys, resource reads and deletion, Session archive, executor credentials, default models, metrics, audit, sandbox deployment and nodes | [Core administration API](../../contracts/agents-api/admin-api.md) | | `/api/v1` | Nodes, Runtime daemons, self-hosted executors and their installers | Machine credentials: node enrollment tokens and node credentials, installation grants, executor credentials, and daemon credentials. Each works only on its own routes | Machine bootstrap and connections under `/api/v1/sandbox-node/*` and `/api/v1/agent-daemon/*`, including WebSockets, and the public native installer downloads | [Machine connection API](../../contracts/agents-api/machine-api.md) | -A credential used in another namespace gets 401: a Project API key on `/core/v1` or `/api/v1`, the Core key on `/v1` or `/api/v1`. How Projects and keys behave is in [Projects own assets](../design-principles.md#projects-own-assets). +A credential used in another namespace gets 401: a Project API key on `/core/v1` or `/api/v1`, the Core key on `/v1` or `/api/v1`. How Projects and keys behave is in [Projects own assets](../concepts.md#projects-own-assets). **Routing.** The reverse proxy sends `/v1` and `/api/v1` to Core and everything else to Web ([proxy setup](../getting-started/install-options.md#https-and-the-reverse-proxy)). Browsers reach `/core/v1` only through Web's console server, which adds the Core key after sign-in and answers 404 for `/v1` and `/api/v1` ([console server](../web/console-server.md)). Operator scripts call `/core/v1` on Core's loopback port ([script the Core API](../getting-started/operations.md#script-the-core-api)). diff --git a/docs/architecture.md b/docs/architecture.md index fcd3566cb..aa3bc0e71 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,93 +1,47 @@ # 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. - -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. +OpenAgentCore separates orchestration, compute and native execution. Core owns the API and durable state. Sandbox Providers manage compute. A Runtime daemon prepares an Environment and runs the selected Harness, whose native SDK or protocol owns the model and tool loop. ```mermaid flowchart TB - App["Application / official SDK"] <-->|"1. Agents API: HTTP / SSE"| Core - Web["Web administrator console"] <-->|"Core management API"| Core - Core["Core
Authorization, configuration snapshots,
orchestration and durable state"] + App["Application / official SDK"] <-->|"Agents API /v1: HTTP and SSE"| Core + Web["Web administrator console"] <-->|"Core API /core/v1"| Core + Core["Core: authorization, configuration snapshots,
orchestration and durable state"] Core --- DB[("PostgreSQL")] - - Core -->|"2. Sandbox Provider contract"| SP["Sandbox Provider adapters
Docker / E2B / microsandbox"] - SP -.->|"Provision the outer Environment,
bootstrap daemon, reclaim compute"| R - User["User runs the installer"] -.->|"Start daemon on a user-owned machine"| R - Core <-->|"3. Core-Runtime protocol
Prepare, execute, cancel, recover;
events and receipts"| R - + Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider: Docker / E2B / microsandbox"] + SP -.->|"Provision compute and bootstrap Runtime"| R + User["User-machine installer"] -.->|"Start Runtime"| R + Core <-->|"Core–Runtime protocol:
preparation, execution, events and receipts"| R subgraph Env["Environment: managed sandbox or user-owned machine"] - R["Runtime / daemon"] - P["Common preparation
Workspace, Skills, Plugins, MCP
Fixed installed.json capability snapshot"] - A["Harness adapters
Codex / Claude / MiniMax"] - H["Native Harness
Model and tool loop"] - F["Workspace, files,
commands and artifacts"] - R --> P - P -->|"4. Harness contract
Executor / Turn / optional capabilities"| A - A <-->|"Native SDK or protocol"| H - H <--> F + R["Runtime daemon"] --> P["Workspace and capability preparation"] + P -->|"Harness protocol"| A["Harness adapter"] + A <-->|"Native SDK or protocol"| H["Native Harness: model and tool loop"] + H <--> F["Workspace, tools and artifacts"] end - - H <-->|"Model API"| Model["Model service"] - H <-->|"MCP protocol"| MCP["MCP servers"] + H <-->|"Model API"| Model["Model provider"] + H <-->|"MCP"| MCP["Local or remote 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. - -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. +Dashed arrows show provisioning and installation. Solid arrows show component interactions, including in-process interfaces. The daemon initiates its authenticated WebSocket connection to Core. The [API index](api/README.md) describes the application, operator and machine namespaces; [protocol boundaries](../AGENTS.md#protocols-at-every-boundary) lists each protocol's code and owning document. -## Core +## Component responsibilities -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. +| Component | Responsibility | Reference | +| --- | --- | --- | +| Core | Authenticate callers, resolve and freeze configuration, schedule Turns, handle cancellation and pending interactions, persist resources and execution facts in PostgreSQL | [Core service](../services/core/README.md) | +| Sandbox Provider | Create, observe, renew and reclaim compute; supply Runtime startup input | [Sandbox Provider](sandbox-provider.md), [Runtime bootstrap](runtime-bootstrap.md) | +| Sandbox node | Operate a Docker or microsandbox host and reconcile its assigned generation and allocations | [Sandbox node protocol](../contracts/agents-api/node-generation-protocol.md) | +| Runtime | Prepare the workspace and capabilities, manage Session Executors, execute Turns and report events and receipts | [Core–Runtime protocol](runtime-protocol.md) | +| Harness adapter | Validate native configuration, invoke the upstream SDK or protocol, translate events and confirm native cleanup | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) | +| Model provider | Serve the model protocol selected for the Harness | [Model execution](../contracts/agents-api/model-execution.md) | +| Web | Let administrators configure and observe the installation through a server-side Core API connection | [Console server](web/console-server.md) | -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 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 [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 capabilities](../contracts/agents-api/harness-capabilities.md) and the [coverage record](../contracts/agents-api/README.md). +The [repository map](development.md#repository-map) locates these components. [Concepts and ownership](concepts.md) explains Project boundaries, administrator authority and tool isolation. ## A Session, end to end -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. - -For workspace Environments, the common path is: - -1. Authenticate the daemon connection and check Harness availability. -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. +An application creates a Session through the Agents API. Core resolves its configuration and execution location. A managed Session obtains compute through the selected Sandbox Provider; a self-hosted Session waits for the user to run its installation command. A Session with `environment: none` uses a connected execution device without a workspace. The [application guide](api/public-agent-api.md#create-a-session) describes these choices. -## Boundaries to keep in mind +After the daemon connects, Core checks the available Harness and requested capabilities. The Runtime prepares a workspace Environment and its capability snapshot, then prepares or reuses the Session Executor. Each Turn runs through the native Harness. Core persists the output, tool interactions and receipts for application reads and events. Completion or cancellation settles the Turn; a healthy Executor can serve the next Turn in the same Environment. -- **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](../contracts/agents-api/model-execution.md#saved-defaults-and-precedence)). -- **Core Web is an administrator console.** It calls only `/core/v1` and cannot start Sessions or send input ([console API usage](web/console-api-usage.md#not-consumed)). +Execution and compute have separate lifetimes: closing an Executor preserves its allocation and workspace until the Provider reclaims them. Preparation, connection and execution readiness have distinct states. The [Environment contract](../contracts/agents-api/environments.md) owns preparation, and the [Core–Runtime protocol](runtime-protocol.md) owns ordering, receipts and failure handling. diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 000000000..855425fcb --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,33 @@ +# Concepts and ownership + +A Project is the execution tenant in OpenAgentCore. Applications use its API keys; operators manage the installation with a separate Core key. The [API index](api/README.md) maps each caller to its namespace and credential. + +## Projects own assets + +A Project owns its Agents, Sessions, Environments, Skills, Files and Vaults. Its named API keys share the same principal, permissions and resources. Core has no product users, roles, memberships or read-only keys. Names are labels; stable IDs identify Projects and keys. + +Projects and keys live in PostgreSQL. Core returns a key's plaintext once, when it is issued. To rotate a key, issue a new one in the same Project, then revoke the old one. Revocation preserves assets, write provenance and accepted work. Archiving a Project revokes all its keys and prevents new keys; administrators retain access to inspect and delete its resources. The [administration contract](../contracts/agents-api/admin-api.md#projects-and-keys) defines these operations. + +The [Core key](getting-started/operations.md#core-key) is a separate deployment credential. An administrator who needs to use the application API issues a Project key and uses that Project's authority. Product users, workspaces and business permissions belong to the application. + +## Resource isolation + +Application reads, writes and references are scoped to the key's Project. A resource in another Project is indistinguishable from an absent one. Core does not share or copy assets across Projects. Nodes, configured model endpoints and startup settings are deployment infrastructure. + +## What administrators can and cannot do + +Administrators manage Projects and keys, sandbox deployments, nodes, executor credentials and deployment default models. They inspect resources, execution history, operational counts and usage, and delete resources under their deletion rules. Archiving a hosted Session requests cancellation and sandbox reclamation; see [Session archive](../contracts/agents-api/admin-api.md#session-archive). + +Creating or editing application assets, starting Sessions and submitting input require a Project API key. The Core key gives no application identity and cannot read stored secrets. The [administration API](../contracts/agents-api/admin-api.md) defines its operations; the [console server](web/console-server.md) owns Web sign-in and credential handling. + +## Runtime and outer isolation + +The Runtime daemon runs on Linux, macOS and Windows. Native platform behavior belongs to the Runtime and its Harness adapters; managed Sandbox Providers run Linux environments. + +Tools run with the permissions of the account that launches the daemon. The daemon adds no filesystem, permission or network isolation. Use the outer Environment for isolation: a managed Docker, E2B or microsandbox environment, or a container or VM around a self-hosted machine's Runtime. Authentication, private storage, locks and process cleanup protect the connection and lifecycle, but tools running as the same user can access Runtime data. + +## Secrets and audit + +Credential values, model keys and confidential template data are write-only: application and administrator reads omit them. Conversation text, Skill source and Artifact content are readable resource data, including to administrators. + +Public writes record the API key responsible. Administrator writes record a separate audit identity and the target Project. Web's actor label is display-only; Core authorizes the Core key. An audit failure rolls back the write. Reads are not audited, and audit records contain no request bodies, secrets or file contents. The [write provenance](../contracts/agents-api/admin-api.md#write-provenance) and [audit log](../contracts/agents-api/admin-api.md#audit-log) contracts define the stored records. diff --git a/docs/design-principles.md b/docs/design-principles.md deleted file mode 100644 index 4df9ed503..000000000 --- a/docs/design-principles.md +++ /dev/null @@ -1,90 +0,0 @@ -# Core design principles - -OpenAgentCore implements the OpenAI Agents API under the -[public API rules](../AGENTS.md#public-api). - -## Three namespaces, three credentials - -Applications, administrators and machines each use their own namespace and -credential. The [API index](api/README.md) owns the complete matrix. - -Separating API authority does not stop an administrator from holding application -credentials: they can issue a Project API key and use it like any application. - -## Projects own assets - -A Project owns one execution tenant and its assets. - -- **Keys.** A Project has one or more named API keys. They share its principal, - permissions and resources. Each write records the key that made it. -- **No users or roles.** Core has no users, roles, memberships or read-only keys. - Names are labels; stable IDs identify Projects and keys. -- **Storage.** Projects and keys live only in PostgreSQL, never in deployment - configuration. A key's plaintext is returned once, at issuance. -- **Rotation.** Issue a new key in the same Project, then revoke the old one. - Revoking a key keeps assets, provenance and accepted work. -- **Archive.** Archiving a Project revokes every key and blocks new ones. - Administrators can still inspect and delete its resources. - -The Core key is a deployment credential, managed separately; see -[Core key](getting-started/operations.md#core-key). Product concepts such as users, -workspaces and business permissions stay outside Core: -a product like Parsar is an ordinary API-key holder in a Project. - -## Resource isolation - -Agents API reads, writes and references are scoped to the key's Project. A resource -in another Project is indistinguishable from an absent one. Nothing is shared or -copied across Projects. Nodes, configured model endpoints and startup settings are -deployment infrastructure, not business assets. - -## What administrators can and cannot do - -| Administrators can | Administrators cannot | -| --- | --- | -| Inspect resources and execution history | Create, copy or edit arbitrary assets | -| Delete resources, under the public deletion rules | Start a Session, send input or cancel work | -| Manage Projects and API keys | Read stored credentials | -| Issue node enrollment tokens and executor credentials | Impersonate an application | -| Query operational counts and usage | | - -Web signs in with the Core key and keeps it on its server; signing in never creates -a Session or gives the browser a Project API key. - -## Runtime and outer isolation - -The same daemon and protocol serve self-hosted Linux, macOS and Windows. OS -differences belong to Runtime implementations; harness differences belong to -adapters. Managed Providers are Linux-only. - -**The daemon is not a sandbox.** It runs tools with its launching user's -permissions and adds no filesystem, permission or network isolation, on any OS. -Isolation comes from the outer Environment: Docker, E2B or microsandbox for managed -Sessions, or whatever container or VM you choose for a self-hosted machine. -Authentication, private storage, locks and process cleanup still apply, but they do -not protect Runtime data from tools running as the same user. - -## Secrets and audit - -- **Write-only secrets.** Credential values, model keys and confidential template - data are never returned by any read, including administrator reads. Conversation - text, Skill source and Artifact content are not secrets: administrators see them. -- **Provenance.** Public writes record their API key. Administrator writes record a - separate audit identity and the target Project. Web's actor label is display-only; - Core trusts the Core key, not the label. -- **Audit is transactional.** An audit failure rolls back the write. Reads are not - audited. Audit records never contain request bodies, secrets or file contents. -- **History.** Resources from the removed copy operation keep their `admin_copy` - ownership, distinct from historical unknown ownership. - -## Out of scope - -Do not add product users, RBAC, cross-Project shared assets, administrator -execution or compatibility with old private protocols. Implementers follow 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 -values. Optional Runtime error metadata is normalized once; it never replaces Core's -terminal authority, cancellation receipts, Usage or native identity. See -[native failure classification](runtime-protocol.md#native-failure-classification). diff --git a/docs/development.md b/docs/development.md index 7160feba1..d9990d9df 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,11 +1,9 @@ # Develop OpenAgentCore -This guide is for contributors changing Core, Runtime, adapters, the Web console -or the documentation site. For using a deployment, start with the -[getting started guide](getting-started/README.md). Read the +Set up a checkout, build a component and validate your changes. To use an installation, start with the [getting started guide](getting-started/README.md). Read the [contributor rules](../CONTRIBUTING.md) before changing code. -![OpenAgentCore architecture: applications and the Web console connect to Core through separate APIs; Sandbox Providers, Runtime, Harnesses and model providers connect through shared protocols.](assets/development-architecture.png) +For component responsibilities and execution flow, read [Architecture](architecture.md). ## Set up a checkout @@ -17,7 +15,7 @@ git worktree add ../openagentcore-change -b codex/my-change main cd ../openagentcore-change ``` -Install Go at the version in [go.mod](../go.mod), Node 22, pnpm at the version +Install Go at the version in [go.mod](../go.mod), Node 22.13 or newer, pnpm at the version in [package.json](../package.json), and Python 3.9 or newer. The complete gate runs on Linux and needs a dedicated PostgreSQL database, OpenSSL development libraries for the microsandbox helper, and a Playwright browser. Provider and @@ -47,8 +45,7 @@ Never point the test suite at an installation or product database. The [test database rules](../CONTRIBUTING.md#test-database) list the required role permission. -Third-party native packages are pinned build inputs; changing a pin requires the -relevant native qualification as well as compilation. +For native package pin changes, follow the [live acceptance rules](../CONTRIBUTING.md#live-acceptance). ## Build and run components @@ -59,10 +56,7 @@ make build-core make build-daemon ``` -These produce the Core commands under `~/.oac/build/oac-core/` and the daemon -under `~/.oac/build/daemon/` by default. `OAC_DEV_HOME` selects another build root; -`OAC_DEV_CORE_BUILD_DIR` selects an absolute Core output directory. Building does -not configure a database, start a deployment or qualify native execution. +Core build outputs and output-directory settings are in [Standalone Core builds](maintainers.md#standalone-core-builds). The daemon is written to `${OAC_DEV_HOME:-$HOME/.oac}/build/daemon/oac-daemon`. Use the [service guide](../services/core/README.md#run-from-source) to run the Core migrator and server with a separate development database. The @@ -71,11 +65,7 @@ owns standalone process settings. For a complete operator installation, use the [installation guide](getting-started/install.md); building Core alone is a separate contributor workflow. -The [Web package guide](../apps/web/README.md) describes console development and -its management-only integration. `pnpm dev:web` starts the frontend development -server; it does not install Core, issue keys or start native execution. The -docs app guide describes the independent documentation -site; `pnpm dev:docs` starts its development server. +For frontend development, run `pnpm dev:web` using the fixture or Core connection in the [Web package guide](../apps/web/README.md). ## Repository map @@ -85,7 +75,7 @@ site; `pnpm dev:docs` starts its development server. | `services/core/internal/store` and `internal/db` | Core persistence, transactions, queries and migrations | [Service guide](../services/core/README.md#database) | | `services/core/internal/execution` | Durable Turn dispatch and scheduling | [Runtime protocol](runtime-protocol.md) | | `services/core/internal/engine` | Pure qualification of harness operations and placements | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) | -| `internal/agentdaemon/proto` and `gateway` | Shared wire types, validators and authenticated Runtime connections | [Runtime protocol](runtime-protocol.md) | +| `internal/agentdaemon/proto` | Core–Runtime wire types and validators | [Runtime protocol](runtime-protocol.md) | | `internal/runtimebootstrap` | Provider-to-Runtime startup input | [Runtime bootstrap](runtime-bootstrap.md) | | `apps/daemon/internal/dispatch` | Runtime preparation, Executor reuse, Turn and cleanup ownership | [Harness lifecycle](../contracts/agents-api/harness-onboarding.md#required-adapter-interfaces) | | `apps/daemon/internal/agent` | Native harness adapters | [Native references](../contracts/agents-api/harness-onboarding.md#native-references) | @@ -93,49 +83,11 @@ site; `pnpm dev:docs` starts its development server. | `services/web` | Console login and the server-side management proxy | [Console server](web/console-server.md) | | `apps/web` and `packages/agents-client` | Console UI and typed clients | [Web guide](../apps/web/README.md) | | `deploy/install` and `scripts` | Distribution, installation and validation tools | [Maintainers](maintainers.md) | -| `contracts/agents-api` | Pinned schema, local semantic contracts and qualification evidence | [Coverage ledger](../contracts/agents-api/README.md) | -| `apps/docs` | Generated guide and API-reference website | Generation workflow | - -Core owns durable execution facts. Runtime owns local execution and cleanup. -Adapters translate native operations. Providers own outer compute. These boundaries -apply to user-owned machines and Core-managed environments; read the -[design principles](design-principles.md) for resource and credential vocabulary. +| `contracts/agents-api` | Pinned schema, semantic contracts and coverage ledger | [Coverage ledger](../contracts/agents-api/README.md) | ## Choose an extension boundary -Each boundary has one canonical guide. Read it before changing code; this page -only helps you pick the right one. - -| Boundary | You are adding or changing | Canonical guide | -| --- | --- | --- | -| Harness adapter | A native agent engine behind the Runtime | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) | -| Sandbox Provider | Outer compute that creates and reclaims Environments | [Sandbox Provider guide](sandbox-provider.md) | -| Runtime bootstrap | Starting a managed Runtime with its connection identity | [Runtime bootstrap](runtime-bootstrap.md) | -| Core–Runtime protocol | A message, receipt or lifecycle rule between Core and the daemon | [Core–Runtime protocol](runtime-protocol.md) | -| Public API operation | A `/v1`, `/core/v1` or `/api/v1` route | [API index](api/README.md) and [contracts](../contracts/agents-api/README.md) | -| Environment capability | Skills, Plugins, MCP or `packages.system` preparation | [Environments](../contracts/agents-api/environments.md#runtime-capability-preparation) | - -### Add a Harness adapter - -Implement the shared `ExecutorFactory`, `Executor` and `Turn` interfaces in -[`agent/harness.go`](../apps/daemon/internal/agent/harness.go), register -the adapter and add its profile/configuration entry to the shared catalog. Follow the numbered steps in -[Harness onboarding](../contracts/agents-api/harness-onboarding.md); qualification -evidence belongs in [Harness capabilities](../contracts/agents-api/harness-capabilities.md). - -### Add a Sandbox Provider - -Implement the five required `SandboxProvider` operations in -[`sandbox_provider.go`](../services/core/internal/sandbox/sandbox_provider.go), -register the provider kind and pass `make check-sandbox-provider-contract`. Follow -the numbered steps in the [Sandbox Provider guide](sandbox-provider.md). - -### Extend the Core–Runtime protocol - -Change shared types and validators in `internal/agentdaemon/proto`, both peers -and their contract tests together, keeping the exact wire-version check. The -[protocol guide](runtime-protocol.md) owns message order, receipts and failure -ownership; `make check-runtime-contract` is its focused gate. +Use the [protocol map](../AGENTS.md#protocols-at-every-boundary) to find the code and guide for a new Harness, Sandbox Provider, model provider, API operation or Runtime message. The guide owns registration, supported operations and the checks that qualify an implementation. For workspace capabilities such as Skills, Plugins, MCP and system packages, start with [Environments](../contracts/agents-api/environments.md). ## Validate a change @@ -153,13 +105,7 @@ Run checks for the affected boundary while developing. The repository | Claude SDK bridge and artifact | `make check-claude-sdk` | | Web UI and clients | `make check-web` | | Distribution or installer | `make check-distribution` | -| Docs sources and generated site | `pnpm --dir apps/docs generate`, then `make check-docs` | - -When the complete change is ready: - -```sh -make check -``` +| Documentation | `make check-names`; `make check-distribution` validates Markdown links and bundled docs | Fixture browser acceptance uses loopback ports 18092 and 4174. Select unused ports with `AGENTS_FIXTURE_PORT` and `AGENTS_WEB_PORT` when running parallel validation. @@ -171,16 +117,6 @@ after validation. ## Change documentation -Edit the source that owns the subject, using the -[documentation ownership map](../CONTRIBUTING.md#documentation-ownership). -User guides explain a workflow and link to detailed contracts. Contributor rules -explain ownership and required checks. Semantic contracts document exact behavior, -implementation gaps and evidence. Avoid copying the same rule into all three. - -Update authored sources before regenerating the docs site. Adding a site page -also requires a source entry and navigation entry; source/output hashes verify -freshness. API references render the namespace-specific generated schemas. Follow -the docs app workflow for link, type, build and browser -checks. The release bundle has a separate explicit documentation list in -`scripts/core-distribution-manifest.py`; changing a bundled path or heading must -also pass its relative-link and anchor checks. +Find the owning source in the [documentation ownership map](../CONTRIBUTING.md#documentation-ownership) and follow the [documentation rules](../AGENTS.md#documentation). Readers use the authored Markdown in the repository. Generated OpenAPI schemas and the Harness catalog have their own generators; see [Contract and schema rules](../CONTRIBUTING.md#contract-and-schema-rules). + +The distribution has an explicit documentation list in `scripts/core-distribution-manifest.py`. When you move a bundled file or change a heading, update its inbound links and run the [distribution documentation checks](maintainers.md#build-a-distribution). diff --git a/docs/examples.md b/docs/examples.md index 91010175f..9ada2a61b 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -15,20 +15,7 @@ no workspace, or on your own machine. Source: [`example/parsar`](../example/parsar/README.md). -### Run it - -You need Node 22.13+, pnpm 10.30.3, a running Core with a default model, and a Project -API key. - -```sh -export OAC_EXAMPLE_CORE_URL='https://core.example' # origin, without /v1 -export OAC_EXAMPLE_PROJECT_KEY='' -pnpm install --frozen-lockfile -pnpm --filter @oac/parsar-example dev -``` - -Open . The example [README](../example/parsar/README.md) covers -storage, a production build, tests and connecting your own machine. +Run and configure it with the [example README](../example/parsar/README.md#run), which also owns its supported features, storage and validation. ### What to look at @@ -44,18 +31,8 @@ Each feature maps to one part of the API. Read the code next to the guide sectio | Follow-ups and cancel | Input events with idempotency keys | [Send input](api/public-agent-api.md#send-input) | [`src/Composer.tsx`](../example/parsar/src/Composer.tsx) | | History | Paging Turns and Items | [Pagination](api/public-agent-api.md#pagination) | [`src/lib/api.ts`](../example/parsar/src/lib/api.ts) | | Skills and versions | `/skills`, default version | [Skills](api/public-agent-api.md#skills) | [`src/Skills.tsx`](../example/parsar/src/Skills.tsx) | -| Connect your own machine | Environment status, executor credential | [Self-hosted execution](getting-started/self-hosted.md) | [`src/ConnectMachine.tsx`](../example/parsar/src/ConnectMachine.tsx) | - -### Not covered - -Vaults and MCP authentication, OAuth, Session deletion, MiniMax Code on your own -machine, and managed Skills or templates on your own machine -(`x_agents_core.environment`). +| Connect your own machine | `x_agents_core.installation`, Environment status | [Self-hosted execution](getting-started/self-hosted.md) | [`src/ConnectMachine.tsx`](../example/parsar/src/ConnectMachine.tsx) | ## Add an example -Put it in its own directory under [`example/`](../example/README.md) with a README -covering how to run it and which API features it shows, then add a row to the -table above. Keep examples on the public API with a Project API key: never the Core -key or private routes. Repository rules for examples are in -[CONTRIBUTING.md](../CONTRIBUTING.md#repository-boundary). +Create a directory under `example/` with a README explaining how to run it and which API features it demonstrates, then add a row to this index. Follow the [application example boundary](../CONTRIBUTING.md#optional-application-example). diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md index 8528e1558..f540a0afb 100644 --- a/docs/getting-started/operations.md +++ b/docs/getting-started/operations.md @@ -107,7 +107,7 @@ A separate Web-only installation keeps its own copy of the key. After rotating, ## Projects and API keys -Create Projects and issue keys in Web, on **Projects and keys**, or through the [Core API](#script-the-core-api). How Projects and keys behave is in [Projects own assets](../design-principles.md#projects-own-assets). +Create Projects and issue keys in Web, on **Projects and keys**, or through the [Core API](#script-the-core-api). How Projects and keys behave is in [Projects own assets](../concepts.md#projects-own-assets). To rotate an application key: @@ -202,4 +202,4 @@ The installer and mutating `oac` commands hold the same installation lock, `.oac Web signs administrators in with the Core key, checks the origin of every request, and forwards signed-in `/core/v1` requests to Core with the Core key, which stays on the server. It answers 404 on `/v1` and `/api/v1` whatever credential a request carries, serves only the non-secret node payload at `/node-install/`, and has no Docker or KVM access. Machine routes under `/api/v1` use their own enrollment and connection credentials. With managed ingress, the `installation` service applies domain changes through the Docker socket; Web reaches it only over a private Unix socket, and it checks the Core key on every request. -Sandboxes are the isolation boundary ([Runtime and outer isolation](../design-principles.md#runtime-and-outer-isolation)). Docker sandboxes share the node's kernel, and a Docker node is [root-equivalent](nodes.md#what-the-installer-sets-up) on its host; microsandbox gives each sandbox a microVM with an explicit [network policy](nodes.md#what-the-installer-sets-up). Core itself has no Docker socket or KVM access. +Sandboxes are the isolation boundary ([Runtime and outer isolation](../concepts.md#runtime-and-outer-isolation)). Docker sandboxes share the node's kernel, and a Docker node is [root-equivalent](nodes.md#what-the-installer-sets-up) on its host; microsandbox gives each sandbox a microVM with an explicit [network policy](nodes.md#what-the-installer-sets-up). Core itself has no Docker socket or KVM access. diff --git a/docs/getting-started/self-hosted.md b/docs/getting-started/self-hosted.md index 7462d3209..bf650fa83 100644 --- a/docs/getting-started/self-hosted.md +++ b/docs/getting-started/self-hosted.md @@ -2,7 +2,7 @@ A `self_hosted` Session runs on a machine your application owns: a workstation, a VM or a sandbox you manage. The application creates the Session through `/v1` and receives a command that installs `oac-daemon`, starts it and connects it to Core. Web shows the same command on the Session's page; it is optional. Core never creates, stops or reclaims the machine. -**The daemon is not a sandbox.** Tools run with the permissions of the account that starts it and can reach whatever that account can. Use a container or VM when you need isolation; see [Runtime and outer isolation](../design-principles.md#runtime-and-outer-isolation). The daemon does not restrict network access, so a Template that requires a network policy is rejected for a self-hosted Session. +**The daemon is not a sandbox.** Tools run with the permissions of the account that starts it and can reach whatever that account can. Use a container or VM when you need isolation; see [Runtime and outer isolation](../concepts.md#runtime-and-outer-isolation). The daemon does not restrict network access, so a Template that requires a network policy is rejected for a self-hosted Session. The Session brings its own model provider; the installation default never applies ([why](../../contracts/agents-api/model-execution.md#saved-defaults-and-precedence)). The machine gets an executor credential that works for this one Environment and nothing else. diff --git a/docs/sandbox-provider.md b/docs/sandbox-provider.md index 0d08b8d6d..a48b4c683 100644 --- a/docs/sandbox-provider.md +++ b/docs/sandbox-provider.md @@ -9,7 +9,7 @@ A **Sandbox Provider** supplies the outer compute that a Runtime daemon runs in | Runtime | The daemon inside the Environment; it prepares capabilities and executes Turns | | Deployment | The single deployment-wide provider selection; see [Sandbox deployment](../contracts/agents-api/sandbox-deployment.md) | -Core owns durable Environment, allocation, placement and cleanup state; the Provider owns compute and bootstrap only. The Runtime prepares capabilities and runs Turns over the [Core–Runtime protocol](runtime-protocol.md), and the provider hands it its identity through the [Runtime bootstrap](runtime-bootstrap.md) file. A provider never runs Environment initialization, Skills, Plugins, MCP setup, initial files, execution or Files; those use the Runtime. Isolation belongs to the provider's infrastructure, not the daemon; see [Runtime and outer isolation](design-principles.md#runtime-and-outer-isolation). Use the vendor's maintained SDK behind a thin adapter. +Core owns durable Environment, allocation, placement and cleanup state; the Provider owns compute and bootstrap only. The Runtime prepares capabilities and runs Turns over the [Core–Runtime protocol](runtime-protocol.md), and the provider hands it its identity through the [Runtime bootstrap](runtime-bootstrap.md) file. A provider never runs Environment initialization, Skills, Plugins, MCP setup, initial files, execution or Files; those use the Runtime. Isolation belongs to the provider's infrastructure, not the daemon; see [Runtime and outer isolation](concepts.md#runtime-and-outer-isolation). Use the vendor's maintained SDK behind a thin adapter. ## Steps diff --git a/docs/web/README.md b/docs/web/README.md index 20d4439e2..f8b018127 100644 --- a/docs/web/README.md +++ b/docs/web/README.md @@ -38,7 +38,7 @@ Missing data is shown as missing (—), never as zero. [Console API usage](conso | Issue, rotate or revoke a self-hosted executor's credential, or copy its install command | The Session's page in the **Session log**; see [self-hosted executors](../getting-started/self-hosted.md) | | Delete a resource, for example a leaked Credential | The resource's row in its list, or its page; Files are deleted from the Files list. The public deletion rules apply | -Installation creates no Project or key. Opening the console neither allocates compute nor calls a model, and an installation may have zero nodes. Web never starts a Session, sends input or cancels work; the [design principles](../design-principles.md#what-administrators-can-and-cannot-do) state what administrators can and cannot do. +Installation creates no Project or key. Opening the console neither allocates compute nor calls a model, and an installation may have zero nodes. Web never starts a Session, sends input or cancels work; the [design principles](../concepts.md#what-administrators-can-and-cannot-do) state what administrators can and cannot do. The deployment's sandbox backend serves hosted Sessions. An application's `self_hosted` Runtime, including one in its own E2B account, is a separate path that the sandbox configuration does not change. diff --git a/example/README.md b/example/README.md deleted file mode 100644 index 34ed492b4..000000000 --- a/example/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Application examples - -Complete applications on the OpenAgentCore public API. See the -[examples guide](../docs/examples.md) for what each one shows and how to run it. - -| Example | Summary | -| --- | --- | -| [Parsar](parsar/README.md) | Agent workbench: models, Skills, MCP, reusable Agents and Sessions on any runtime | diff --git a/packages/claude-sdk-adapter/README.md b/packages/claude-sdk-adapter/README.md index 2a4b826cf..26b3497d9 100644 --- a/packages/claude-sdk-adapter/README.md +++ b/packages/claude-sdk-adapter/README.md @@ -26,7 +26,7 @@ With `observe_messages`, it also emits the neutral `output_message` start/comple ### Workspace execution -`claudesdk.Config.Workspace` is an operator binding for the selected workspace and native state. It enables native Bash/Read/Edit and admitted host functions in the SDK loop. Native tools run with the launching user's permissions on all platforms; the adapter adds no inner sandbox, protected-root deny policy or managed shell wrapper. Isolation belongs to the outer Environment ([Runtime and outer isolation](../../docs/design-principles.md#runtime-and-outer-isolation)), which must exclude other tenants' and broader application credentials; an ordinary native install provides no such boundary, and directory selection is not tenant authorization. The adapter's tool callback authorizes unattended execution in native `default` permission mode. It does not use the CLI permission-bypass flag, which Claude rejects for root accounts. +`claudesdk.Config.Workspace` is an operator binding for the selected workspace and native state. It enables native Bash/Read/Edit and admitted host functions in the SDK loop. Native tools run with the launching user's permissions on all platforms; the adapter adds no inner sandbox, protected-root deny policy or managed shell wrapper. Isolation belongs to the outer Environment ([Runtime and outer isolation](../../docs/concepts.md#runtime-and-outer-isolation)), which must exclude other tenants' and broader application credentials; an ordinary native install provides no such boundary, and directory selection is not tenant authorization. The adapter's tool callback authorizes unattended execution in native `default` permission mode. It does not use the CLI permission-bypass flag, which Claude rejects for root accounts. `Config.Env` selects readiness and native process variables. Explicit tool env is applied to tool execution, but same-user tools can still read credentials or history from local files. Workspace hooks keep their event, identity and lifecycle responsibilities; they are not security enforcement. Process groups and Windows Jobs provide cancellation and descendant cleanup, not isolation. Supported MCP and subagent combinations require their own qualification. The `none` profile keeps its tool inventory. Packaged `workspace_tools` establishes bridge support, not outer host isolation or public API admission. The dedicated Runtime composes public preparation, placement quotas, command Items and Files ownership. Real-provider acceptance verifies effects, cancellation and same-history continuation for the actual platform and outer deployment. From c9991a9aa2ad1fe3a9aab5eae5a94256058790e6 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:18:47 +0000 Subject: [PATCH 2/7] docs: unwrap prose in top-level guides --- README.md | 22 +++++++--------------- README.zh-CN.md | 9 +++------ docs/development.md | 36 +++++++----------------------------- docs/examples.md | 7 ++----- 4 files changed, 19 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index c0d7050e9..627541c7c 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,10 @@ An open-source, self-hosted implementation of the OpenAI Agents API with multipl OpenAgentCore runs AI agents on your own infrastructure behind the OpenAI Agents API. -- **Same API as OpenAI.** Point the official OpenAI SDK, or plain HTTP, at your - installation. No new client to learn. -- **Your choice of agent.** Each Session runs a native harness: Codex, Claude Code or - MiniMax Code, with the model provider you configure. -- **Your choice of machine.** Agents work in a managed sandbox (Docker, microsandbox - or E2B), or on your own Linux, macOS or Windows machine. -- **Every part is replaceable.** Sandboxes, harnesses and model providers plug in - through defined protocols. +- **Same API as OpenAI.** Point the official OpenAI SDK, or plain HTTP, at your installation. No new client to learn. +- **Your choice of agent.** Each Session runs a native harness: Codex, Claude Code or MiniMax Code, with the model provider you configure. +- **Your choice of machine.** Agents work in a managed sandbox (Docker, microsandbox or E2B), or on your own Linux, macOS or Windows machine. +- **Every part is replaceable.** Sandboxes, harnesses and model providers plug in through defined protocols. ## Screenshots @@ -46,8 +42,7 @@ Then: 3. **Add execution capacity:** a node, E2B, or your own machine. 4. **[Run your first Session](docs/getting-started/quickstart.md)** with the OpenAI SDK. -The [installation guide](docs/getting-started/install.md) covers each step, HTTPS -and a quick local trial. Listen addresses, ports and other options: [installation options](docs/getting-started/install-options.md). +The [installation guide](docs/getting-started/install.md) covers each step, HTTPS and a quick local trial. Listen addresses, ports and other options: [installation options](docs/getting-started/install-options.md). ## How it fits together @@ -60,9 +55,7 @@ Applications and operators use these Core APIs: | **[Agents API](docs/api/public-agent-api.md)** | `/v1` | Your applications. Same protocol as [OpenAI's Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) | | **[Core API](contracts/agents-api/admin-api.md)** | `/core/v1` | Operators, through Web | -Core keeps durable execution state. The Runtime runs the chosen harness inside the Environment. -Each connection is a defined protocol, so any part can be replaced on its own. See -the [architecture guide](docs/architecture.md). +Core keeps durable execution state. The Runtime runs the chosen harness inside the Environment. Each connection is a defined protocol, so any part can be replaced on its own. See the [architecture guide](docs/architecture.md). ## Documentation @@ -76,5 +69,4 @@ the [architecture guide](docs/architecture.md). | Understand the design | [Architecture](docs/architecture.md) | | Add a sandbox, harness or other component | [Developer guide](docs/development.md) | -All pages: [documentation index](docs/getting-started/README.md). Before changing -code, read the [contributor rules](CONTRIBUTING.md). +All pages: [documentation index](docs/getting-started/README.md). Before changing code, read the [contributor rules](CONTRIBUTING.md). diff --git a/README.zh-CN.md b/README.zh-CN.md index 1a6fea695..ff9c43f68 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,10 +17,8 @@ OpenAI Agents API 的开源实现，支持多种原生执行引擎，可部署 OpenAgentCore 在你自己的基础设施上运行 AI Agent，对外提供 OpenAI Agents API。 - **与 OpenAI 相同的 API。** 官方 OpenAI SDK 或直接 HTTP 调用，改一下地址即可，无需学习新客户端。 -- **自选 Agent。** 每个 Session 运行一个原生 Harness：Codex、Claude Code 或 MiniMax Code， - 使用你配置的模型供应商。 -- **自选机器。** Agent 可以在托管沙箱（Docker、microsandbox 或 E2B）里工作， - 也可以在你自己的 Linux、macOS 或 Windows 机器上工作。 +- **自选 Agent。** 每个 Session 运行一个原生 Harness：Codex、Claude Code 或 MiniMax Code， 使用你配置的模型供应商。 +- **自选机器。** Agent 可以在托管沙箱（Docker、microsandbox 或 E2B）里工作， 也可以在你自己的 Linux、macOS 或 Windows 机器上工作。 - **每个部件都可替换。** 沙箱、Harness 和模型供应商都通过既定协议接入。 ## 界面预览 @@ -57,8 +55,7 @@ curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/ | **[Agents API](docs/api/public-agent-api.md)** | `/v1` | 你的应用，与 [OpenAI 的 Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) 协议一致 | | **[Core API](contracts/agents-api/admin-api.md)** | `/core/v1` | 管理员，通过 Web 调用 | -持久化执行状态由 Core 保存；Runtime 在 Environment 中运行所选 Harness。各部件之间都通过既定协议连接， -任何一个都可以单独替换。详见[架构说明](docs/architecture.md)。 +持久化执行状态由 Core 保存；Runtime 在 Environment 中运行所选 Harness。各部件之间都通过既定协议连接， 任何一个都可以单独替换。详见[架构说明](docs/architecture.md)。 ## 文档 diff --git a/docs/development.md b/docs/development.md index d9990d9df..ca559a302 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,25 +1,19 @@ # Develop OpenAgentCore -Set up a checkout, build a component and validate your changes. To use an installation, start with the [getting started guide](getting-started/README.md). Read the -[contributor rules](../CONTRIBUTING.md) before changing code. +Set up a checkout, build a component and validate your changes. To use an installation, start with the [getting started guide](getting-started/README.md). Read the [contributor rules](../CONTRIBUTING.md) before changing code. For component responsibilities and execution flow, read [Architecture](architecture.md). ## Set up a checkout -Work from an isolated worktree so experiments and validation do not disturb -another checkout. From an existing clone with an up-to-date `main`: +Work from an isolated worktree so experiments and validation do not disturb another checkout. From an existing clone with an up-to-date `main`: ```sh git worktree add ../openagentcore-change -b codex/my-change main cd ../openagentcore-change ``` -Install Go at the version in [go.mod](../go.mod), Node 22.13 or newer, pnpm at the version -in [package.json](../package.json), and Python 3.9 or newer. The complete gate -runs on Linux and needs a dedicated PostgreSQL database, OpenSSL development -libraries for the microsandbox helper, and a Playwright browser. Provider and -Runtime builds have additional prerequisites in their component guides. +Install Go at the version in [go.mod](../go.mod), Node 22.13 or newer, pnpm at the version in [package.json](../package.json), and Python 3.9 or newer. The complete gate runs on Linux and needs a dedicated PostgreSQL database, OpenSSL development libraries for the microsandbox helper, and a Playwright browser. Provider and Runtime builds have additional prerequisites in their component guides. ```sh pnpm install --frozen-lockfile @@ -40,10 +34,7 @@ pnpm exec playwright install --with-deps chrome export OAC_TEST_OFFICIAL_SDK_PYTHON="$PWD/.venv/bin/python" ``` -Set `OAC_TEST_DATABASE_URL` privately to a dedicated PostgreSQL test database. -Never point the test suite at an installation or product database. The -[test database rules](../CONTRIBUTING.md#test-database) list the required role -permission. +Set `OAC_TEST_DATABASE_URL` privately to a dedicated PostgreSQL test database. Never point the test suite at an installation or product database. The [test database rules](../CONTRIBUTING.md#test-database) list the required role permission. For native package pin changes, follow the [live acceptance rules](../CONTRIBUTING.md#live-acceptance). @@ -58,12 +49,7 @@ make build-daemon Core build outputs and output-directory settings are in [Standalone Core builds](maintainers.md#standalone-core-builds). The daemon is written to `${OAC_DEV_HOME:-$HOME/.oac}/build/daemon/oac-daemon`. -Use the [service guide](../services/core/README.md#run-from-source) -to run the Core migrator and server with a separate development database. The -[configuration appendix](configuration.md#appendix-core-environment-without-the-installer) -owns standalone process settings. For a complete operator installation, use the -[installation guide](getting-started/install.md); building Core alone is a -separate contributor workflow. +Use the [service guide](../services/core/README.md#run-from-source) to run the Core migrator and server with a separate development database. The [configuration appendix](configuration.md#appendix-core-environment-without-the-installer) owns standalone process settings. For a complete operator installation, use the [installation guide](getting-started/install.md); building Core alone is a separate contributor workflow. For frontend development, run `pnpm dev:web` using the fixture or Core connection in the [Web package guide](../apps/web/README.md). @@ -91,9 +77,7 @@ Use the [protocol map](../AGENTS.md#protocols-at-every-boundary) to find the cod ## Validate a change -Run checks for the affected boundary while developing. The repository -[required checks](../CONTRIBUTING.md#required-checks) define completion, including -`make check` and any changed native component's real acceptance. +Run checks for the affected boundary while developing. The repository [required checks](../CONTRIBUTING.md#required-checks) define completion, including `make check` and any changed native component's real acceptance. | Change | Focused validation | | --- | --- | @@ -107,13 +91,7 @@ Run checks for the affected boundary while developing. The repository | Distribution or installer | `make check-distribution` | | Documentation | `make check-names`; `make check-distribution` validates Markdown links and bundled docs | -Fixture browser acceptance uses loopback ports 18092 and 4174. Select unused ports -with `AGENTS_FIXTURE_PORT` and `AGENTS_WEB_PORT` when running parallel validation. -Keep databases, ports and containers separate between validation workers. -Compilation, fixture success and live model/provider acceptance establish different -facts; report skipped or unavailable checks explicitly. Follow the -[independent blind review workflow](../CONTRIBUTING.md#review) -after validation. +Fixture browser acceptance uses loopback ports 18092 and 4174. Select unused ports with `AGENTS_FIXTURE_PORT` and `AGENTS_WEB_PORT` when running parallel validation. Keep databases, ports and containers separate between validation workers. Compilation, fixture success and live model/provider acceptance establish different facts; report skipped or unavailable checks explicitly. Follow the [independent blind review workflow](../CONTRIBUTING.md#review) after validation. ## Change documentation diff --git a/docs/examples.md b/docs/examples.md index 9ada2a61b..73e8421aa 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,7 +1,6 @@ # Examples -Complete applications built on the [Agents API](api/public-agent-api.md). Each one -runs against a real Core installation with a Project API key. +Complete applications built on the [Agents API](api/public-agent-api.md). Each one runs against a real Core installation with a Project API key. | Example | What it shows | | --- | --- | @@ -9,9 +8,7 @@ runs against a real Core installation with a Project API key. ## Parsar Agent workbench -A small single-user product built on Core. You save model providers, Skills and MCP -servers, combine them into Agents, then start Sessions in a managed sandbox, with -no workspace, or on your own machine. +A small single-user product built on Core. You save model providers, Skills and MCP servers, combine them into Agents, then start Sessions in a managed sandbox, with no workspace, or on your own machine. Source: [`example/parsar`](../example/parsar/README.md). From ec8792ccf3189a1a3dab1e0cf3cd167e5a020729 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:21:33 +0000 Subject: [PATCH 3/7] docs: centralize process settings and remove stale site guidance --- apps/web/DESIGN.md | 2 +- apps/web/PRODUCT.md | 2 +- contracts/agents-api/environments.md | 2 +- deploy/install/README.md | 2 +- docs/configuration.md | 24 +++++++++++++++++++++--- docs/web/README.md | 2 +- docs/web/console-server.md | 19 ++----------------- scripts/core-distribution-manifest.py | 1 - scripts/name-allowlist.json | 5 ----- 9 files changed, 28 insertions(+), 31 deletions(-) diff --git a/apps/web/DESIGN.md b/apps/web/DESIGN.md index 8efa23278..c755b00f6 100644 --- a/apps/web/DESIGN.md +++ b/apps/web/DESIGN.md @@ -236,7 +236,7 @@ The data contract is part of the look. Core reports only what it observes, so th A restrained neutral ledger with one indigo voice, three signal colours and a separate categorical palette that belongs to multi-series data alone. ### Primary -- **OpenAgentCore Indigo** (accent): keyboard focus outlines and rings, the focus ring of fields, the text caret and the text selection wash. Deepens to **Pressed Indigo** (accent-emphasis) for hovered name links. It is the console's only accent; the public landing (`site/`) uses its own violet, `#5a43c7`. +- **OpenAgentCore Indigo** (accent): keyboard focus outlines and rings, the focus ring of fields, the text caret and the text selection wash. Deepens to **Pressed Indigo** (accent-emphasis) for hovered name links. It is the console's only accent. - **Data** (`--data`, the same colour as Series 1, a lighter indigo): the one measured series of a chart that has only one, such as Sessions created per hour on Overview, drawn as a tint (62% into the surface) rather than full strength. ### Neutral diff --git a/apps/web/PRODUCT.md b/apps/web/PRODUCT.md index 4cf436bf1..c9de6dcd6 100644 --- a/apps/web/PRODUCT.md +++ b/apps/web/PRODUCT.md @@ -67,7 +67,7 @@ The console runs beside the administrator's own Core, with execution, files and ## Brand Commitments - Product name: OpenAgentCore. OpenAgentCore mark assets in `apps/web/public/`. -- Keep the OpenAgentCore visual identity shared with the public landing (`site/`): neutral grays and a quiet indigo accent. The console uses Inter and Geist Mono on Beautiful UI's foundation tokens and structure; `DESIGN.md` records the system. +- Use the OpenAgentCore visual identity: neutral grays and a quiet indigo accent. The console uses Inter and Geist Mono on Beautiful UI's foundation tokens and structure; `DESIGN.md` records the system. ## Evidence on Hand diff --git a/contracts/agents-api/environments.md b/contracts/agents-api/environments.md index cb20c1f01..a20e10e88 100644 --- a/contracts/agents-api/environments.md +++ b/contracts/agents-api/environments.md @@ -8,7 +8,7 @@ Related owners: - [Executor credentials](environment-executor-credentials.md): enrollment, the installation grant and connection status of a `self_hosted` machine. - [Sandbox deployment](sandbox-deployment.md): which Sandbox Provider (E2B, Docker or microsandbox) hosts `openai_hosted` Environments. - [Core–Runtime protocol](../../docs/runtime-protocol.md): the `runtime_prepare` transfer and every other wire message. -- [Runtime and outer isolation](../../docs/design-principles.md#runtime-and-outer-isolation): the daemon runs tools with its launching user's permissions; isolation comes from the outer Environment. +- [Runtime and outer isolation](../../docs/concepts.md#runtime-and-outer-isolation): the daemon runs tools with its launching user's permissions; isolation comes from the outer Environment. ## Resources and states diff --git a/deploy/install/README.md b/deploy/install/README.md index 378807681..0861ac60a 100644 --- a/deploy/install/README.md +++ b/deploy/install/README.md @@ -146,4 +146,4 @@ The Core and node installers share one resolver for these identities. It confirm ## Validation -`make check-distribution` covers the production proxy, the installation rules, release metadata and native catalog assembly, including bundle manifests larger than Node's default subprocess buffer (catalog assembly reads up to 64 MiB). Diagnostics report observed service health, never fabricated model or environment readiness. Runtime observations belong to Core; do not add monitoring or lifecycle tracking to the installer or the landing site. +`make check-distribution` covers the production proxy, the installation rules, release metadata and native catalog assembly, including bundle manifests larger than Node's default subprocess buffer (catalog assembly reads up to 64 MiB). Diagnostics report observed service health, never fabricated model or environment readiness. Runtime observations belong to Core; do not add monitoring or lifecycle tracking to the installer. diff --git a/docs/configuration.md b/docs/configuration.md index 852f5070d..202f955de 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -139,14 +139,15 @@ Core reads only its environment. The installer renders `generated/core.env` from | Variable | Set from | | --- | --- | | `OAC_PUBLIC_URL` | `public_url`, or Core's loopback origin. Core derives the daemon WebSocket URL, the self-hosted `remote_url`, the hosted sandbox address and the deployment's read-only `core_url` from it, never from request headers. Without it, Core runs no Runtime gateway and executes no Sessions | -| `OAC_ADDR` | `ports.core` (native Core) or `:8091` in the container | +| `OAC_ADDR` | The installer derives the native listener from `ports.core` and sets `:8091` in the container. Independently started Core defaults to `127.0.0.1:8091` when unset or empty | | `OAC_DATABASE_URL` | The installation's PostgreSQL without a password, plus `core.database_pool` as `pool_*` query parameters | | `OAC_DATABASE_PASSWORD_FILE` | `secrets/database.password`. The URL must then carry no password; migrations and the maintenance commands read the file too | | `OAC_CREDENTIAL_KEY_FILE` | `secrets/credential.key` | | `OAC_CORE_KEY_DIGESTS_FILE` | `generated/core-key-digests.json`: a JSON array with the SHA-256 of the Core key | | `OAC_INSTALLATION_ID` | The installation ID from `state.json`, a canonical UUID. It enables the sandbox deployment and node routes and requires `OAC_PUBLIC_URL` and `OAC_CORE_KEY_DIGESTS_FILE`. Core refuses an ID other than the one its database recorded, so keep the two together | | `OAC_SETTINGS_FILE` | `generated/settings.json`, the snapshot Core serves at `GET /core/v1/installation`; Core does not act on it | -| `OAC_EXECUTION_CONCURRENCY`, `OAC_DEFAULT_HARNESS`, `OAC_HARNESSES`, `OAC_WRITE_AUDIT_RETENTION`, `OAC_OAUTH_TRUSTED_ORIGINS` | The matching `core.*` settings | +| `OAC_EXECUTION_CONCURRENCY`, `OAC_DEFAULT_HARNESS`, `OAC_WRITE_AUDIT_RETENTION`, `OAC_OAUTH_TRUSTED_ORIGINS` | The matching [process settings](#settings); omitted or empty default Harness uses `core.default_harness`’s documented default | +| `OAC_HARNESSES` | `core.harnesses` with the installer. Independently started Core enables only the default Harness when unset; comma-separated explicit names supplement it. Entries are trimmed and deduplicated; unknown names stop startup | | `OAC_HISTORY_SETTINGS_FILE` | `generated/runtime-history.json`: the [`core.runtime_history`](#settings) object, when it is set | | `OAC_LOG_LEVEL`, `OAC_LOG_FORMAT`, `OAC_LOG_ADD_SOURCE` | `log.*`; Web reads the same three | | `OAC_PROVIDER_ROOT` | Absolute adapter artifact root: `native/` for native Core, `/opt/oac` in the Core image. Each adapter owns its helper paths beneath this root | @@ -155,4 +156,21 @@ Core reads only its environment. The installer renders `generated/core.env` from Core logs the file paths it loads, never environment values or file contents. -A Web you run without the installer reads the variables in [Console server settings](web/console-server.md#settings), plus `OAC_WEB_NODE_PAYLOAD_DIR`: the absolute path of the matched distribution's node payload (the installer's `node-payload/`). Without it, Add node is unavailable. +Invalid explicit OAuth trusted origins stop Core at startup. Entries must be HTTPS origins without credentials, query or a non-root path; the installer validates `core.oauth_trusted_origins` before generating them. [Vaults](../contracts/agents-api/vaults.md) owns refresh and network policy. A private issuer also needs a trusted CA: independently managed Unix Core can use Go’s `SSL_CERT_FILE` PEM CA-bundle override, which preserves certificate verification. Managed installation has no custom-CA setting or mount; do not edit `generated/core.env`. + +## Appendix: Web environment without the installer + +The installer sets these variables from `config.json`; set them yourself only when you run the console without the installer. Of the installation's secrets, the installer gives the console only `secrets/core.key`. + +| Variable | Default | Meaning | +| --- | --- | --- | +| `OAC_WEB_ADDR` | `:8080` | Listener address | +| `OAC_WEB_ORIGIN` | `http://127.0.0.1:8080` | The exact browser-facing origin, HTTP or HTTPS, without a path. Host and origin checks use it; HTTPS makes the session cookie `Secure` | +| `OAC_WEB_UPSTREAM` | `http://core:8091` | Core's origin, HTTP or HTTPS, without credentials, query or path | +| `OAC_WEB_CORE_KEY_FILE` | `/admin/core.key` | Absolute path of a regular file with no group or other permissions, holding the Core key: at least 32 characters, no whitespace, at most 4 KiB | +| `OAC_WEB_DIST` | `/www` | Absolute directory of the built console; must contain `index.html` | +| `OAC_WEB_NODE_PAYLOAD_DIR` | unset | Absolute path of the matched distribution's node payload (the installer's `node-payload/`). Unset, `/node-install/*` is not served and Add node is unavailable | +| `OAC_WEB_INSTALLATION_SOCKET` | unset | Absolute path of the installer's domain socket. Unset, domain setup reports unsupported | +| `OAC_WEB_BOOTSTRAP` | `0` | `1` accepts literal-IP hosts before a domain is configured. Requires an `http://` origin and `OAC_WEB_INSTALLATION_SOCKET` | + +Defaults apply when a variable is absent; an explicitly empty value is validated as supplied. An invalid `OAC_WEB_*` value stops the console at startup with a message naming the variable. The console also reads `OAC_LOG_LEVEL`, `OAC_LOG_FORMAT` and `OAC_LOG_ADD_SOURCE` ([Core environment](#appendix-core-environment-without-the-installer)); unknown values fall back to their defaults. Use HTTPS for any browser that is not on the same machine. diff --git a/docs/web/README.md b/docs/web/README.md index f8b018127..0c6dc6931 100644 --- a/docs/web/README.md +++ b/docs/web/README.md @@ -38,7 +38,7 @@ Missing data is shown as missing (—), never as zero. [Console API usage](conso | Issue, rotate or revoke a self-hosted executor's credential, or copy its install command | The Session's page in the **Session log**; see [self-hosted executors](../getting-started/self-hosted.md) | | Delete a resource, for example a leaked Credential | The resource's row in its list, or its page; Files are deleted from the Files list. The public deletion rules apply | -Installation creates no Project or key. Opening the console neither allocates compute nor calls a model, and an installation may have zero nodes. Web never starts a Session, sends input or cancels work; the [design principles](../concepts.md#what-administrators-can-and-cannot-do) state what administrators can and cannot do. +Installation creates no Project or key. Opening the console neither allocates compute nor calls a model, and an installation may have zero nodes. Web never starts a Session or sends input. Archiving a hosted Session requests cancellation and reclamation; [administrator authority](../concepts.md#what-administrators-can-and-cannot-do) state what administrators can and cannot do. The deployment's sandbox backend serves hosted Sessions. An application's `self_hosted` Runtime, including one in its own E2B account, is a separate path that the sandbox configuration does not change. diff --git a/docs/web/console-server.md b/docs/web/console-server.md index b4c5165b7..78a891b00 100644 --- a/docs/web/console-server.md +++ b/docs/web/console-server.md @@ -2,6 +2,8 @@ The console server (`services/web`, the `oac-web` process) serves the built console, signs the administrator in with the Core key and forwards the signed-in browser's `/core/v1` requests to Core with that key. The browser never holds the Core key or any API key. Applications, nodes and self-hosted executors call Core directly; the console forwards none of their traffic. +[Configuration](../configuration.md#appendix-web-environment-without-the-installer) owns its process settings and defaults. + ## Request boundary ```mermaid @@ -110,23 +112,6 @@ The System page submits a hostname once, polls the status every 2 seconds while `OAC_WEB_BOOTSTRAP=1`, which the installer sets while no public URL is configured, lets the console also accept plain HTTP requests addressed to a literal IP address, treating `http://` as the origin, so an operator can sign in through the server's IP address. Host names still require `OAC_WEB_ORIGIN`, so DNS rebinding cannot reach the console. -## Settings - -The installer sets these variables from `config.json`; set them yourself only when you run the console without the installer. Of the installation's secrets, the installer gives the console only `secrets/core.key`. - -| Variable | Default | Meaning | -| --- | --- | --- | -| `OAC_WEB_ADDR` | `:8080` | Listener address | -| `OAC_WEB_ORIGIN` | `http://127.0.0.1:8080` | The exact browser-facing origin, HTTP or HTTPS, without a path. Host and origin checks use it; HTTPS makes the session cookie `Secure` | -| `OAC_WEB_UPSTREAM` | `http://core:8091` | Core's origin, HTTP or HTTPS, without credentials, query or path | -| `OAC_WEB_CORE_KEY_FILE` | `/admin/core.key` | Absolute path of a regular file with no group or other permissions, holding the Core key: at least 32 characters, no whitespace, at most 4 KiB | -| `OAC_WEB_DIST` | `/www` | Absolute directory of the built console; must contain `index.html` | -| `OAC_WEB_NODE_PAYLOAD_DIR` | unset | Absolute path of the matched distribution's node payload (the installer's `node-payload/`). Unset, `/node-install/*` is not served and Add node is unavailable | -| `OAC_WEB_INSTALLATION_SOCKET` | unset | Absolute path of the installer's domain socket. Unset, domain setup reports unsupported | -| `OAC_WEB_BOOTSTRAP` | `0` | `1` accepts literal-IP hosts before a domain is configured. Requires an `http://` origin and `OAC_WEB_INSTALLATION_SOCKET` | - -An invalid `OAC_WEB_*` value stops the console at startup with a message naming the variable. The console also reads `OAC_LOG_LEVEL`, `OAC_LOG_FORMAT` and `OAC_LOG_ADD_SOURCE` ([configuration](../configuration.md#appendix-core-environment-without-the-installer)); unknown values fall back to their defaults. Use HTTPS for any browser that is not on the same machine. - ## Verification After installing or changing the console, check: diff --git a/scripts/core-distribution-manifest.py b/scripts/core-distribution-manifest.py index 828b7e43c..d24166278 100644 --- a/scripts/core-distribution-manifest.py +++ b/scripts/core-distribution-manifest.py @@ -50,7 +50,6 @@ BUNDLED_FILES = ( "docs/assets/openagentcore-banner.jpeg", "docs/assets/architecture.png", - "docs/assets/development-architecture.png", "docs/assets/console-overview-en.webp", "docs/assets/console-overview-zh.webp", "docs/assets/console-agent-metrics-en.webp", diff --git a/scripts/name-allowlist.json b/scripts/name-allowlist.json index 73e0c9a1a..ab35a8e29 100644 --- a/scripts/name-allowlist.json +++ b/scripts/name-allowlist.json @@ -204,11 +204,6 @@ "regex": "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": "docs/design-principles.md", - "regex": "Parsar is an ordinary API-key holder", - "reason": "These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." - }, { "path": "apps/web/PRODUCT.md", "regex": "and Parsar itself", From 3285ff76a1d873b08db23797502b014d8b1b72f3 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:24:39 +0000 Subject: [PATCH 4/7] docs: name the sandbox node protocol consistently --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5e9ee808f..b5f732746 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ OpenAgentCore is protocol-first and modular. Core orchestrates operations that p | Web and operators–Core (`/core/v1`) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/core.openapi.yaml` | [Core administration API](contracts/agents-api/admin-api.md) | | Nodes and daemons–Core (`/api/v1` HTTP routes; the node and daemon wire protocols are separate rows) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](contracts/agents-api/machine-api.md) | | Core–Sandbox Provider | `services/core/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) | -| Core–sandbox node | `services/core/internal/sandbox/node/wire.go` | [Node generation protocol](contracts/agents-api/node-generation-protocol.md) | +| Core–sandbox node | `services/core/internal/sandbox/node/wire.go` | [Sandbox node 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/daemon/internal/agent/harness.go` | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | From a6464a1d30cfd74a0c0cb64627cd1bdd972d9061 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:26:27 +0000 Subject: [PATCH 5/7] docs: move shared Docker settings to their owning guides --- CONTRIBUTING.md | 2 +- docs/configuration.md | 14 ++++++++++++++ docs/runtime-protocol.md | 2 +- docs/sandbox-provider.md | 20 +++++++++++++++++++- services/core/deploy/claude/README.md | 4 ++-- services/core/deploy/codex/README.md | 20 ++------------------ services/core/deploy/e2b/README.md | 2 +- services/core/deploy/mcode/README.md | 4 ++-- 8 files changed, 42 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be8f11c40..c137207c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ This guide owns how to work in the repository: documentation ownership, the repo | 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 semantics and protocol coverage | [Agents API contracts](contracts/agents-api/README.md) | -| Machine connection routes | [Machine connection API](docs/api/README.md#machine-connection-api) | +| Machine connection routes | [Machine connection API](contracts/agents-api/machine-api.md) | | Core service setup, tests and generation | [Core service guide](services/core/README.md) | | Core implementation constraints beyond the public contracts | [Implementation constraints](services/core/IMPLEMENTATION.md) | | Environment ownership, preparation, Skills, Plugins, packages and MCP bindings | [Environments](contracts/agents-api/environments.md) | diff --git a/docs/configuration.md b/docs/configuration.md index 202f955de..e12d52e9c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -108,6 +108,20 @@ Core approves a node's capacity when you generate its Add node command: **Sandbo Set a default in **System** → **Default model configuration**, or use `PUT /core/v1/harnesses/{harness}/model-configuration`. Core encrypts provider keys with `secrets/credential.key` and never returns them. [Model execution](../contracts/agents-api/model-execution.md#deployment-defaults) owns the request fields and replacement rules, and [precedence](../contracts/agents-api/model-execution.md#saved-defaults-and-precedence) says which Sessions use a default. +## Docker node configuration + +The node installer writes Docker’s provider configuration into the node’s configuration file; these fields are separate from Core’s `config.json`. Deployment resources, Runtime images and capacity remain in [Core’s database](#runtime-settings-web). + +| Field | Installer value | Meaning | +| --- | --- | --- | +| `host` | `unix:///var/run/docker.sock` | Explicit Docker Engine socket | +| `network` | `oac-node-` | Runtime container network | +| `seccomp_file` | `/runtime/seccomp.json` | Matched distribution’s seccomp profile | +| `nested_sandbox` | `true` | Enables the Docker adapter’s init process and proc-mask configuration | +| `extra_hosts` | Optional | Additional container host mappings | + +The [Docker adapter](sandbox-provider.md#docker-adapter) owns container isolation, volume layout and lifecycle behavior. + ## Installation directory The installer creates the installation directory, `~/.oac/core` by default, with mode `0700`; the files in `secrets/` are `0600`. diff --git a/docs/runtime-protocol.md b/docs/runtime-protocol.md index d6b4e8b56..1a7e1d4fc 100644 --- a/docs/runtime-protocol.md +++ b/docs/runtime-protocol.md @@ -6,7 +6,7 @@ Hosted and self-hosted Runtimes use the same protocol. A Harness joins through t ## Ownership and connection -Core owns durable Session, Turn, input and Environment records, scheduling and reconciliation. Runtime owns native Executors, active Turns, transfer state and cleanup until settlement. A Sandbox Provider owns placement and the surrounding compute. Releasing an execution admission or closing an Executor never deletes, suspends or reclaims a sandbox. The daemon is not an isolation boundary; see [Runtime and outer isolation](design-principles.md#runtime-and-outer-isolation). +Core owns durable Session, Turn, input and Environment records, scheduling and reconciliation. Runtime owns native Executors, active Turns, transfer state and cleanup until settlement. A Sandbox Provider owns placement and the surrounding compute. Releasing an execution admission or closing an Executor never deletes, suspends or reclaims a sandbox. The daemon is not an isolation boundary; see [Runtime and outer isolation](concepts.md#runtime-and-outer-isolation). A Runtime connects in this order: diff --git a/docs/sandbox-provider.md b/docs/sandbox-provider.md index a48b4c683..32c51eccd 100644 --- a/docs/sandbox-provider.md +++ b/docs/sandbox-provider.md @@ -206,6 +206,24 @@ Native acceptance proves what fixtures cannot: creation, lease behavior, owned p | Kind | Adapter | Helper and adapter rules | Operator guide | | --- | --- | --- | --- | -| Docker (node) | [`sandbox/docker`](../services/core/internal/sandbox/docker) | Node proxy in [`sandbox/node`](../services/core/internal/sandbox/node); [Docker sandbox settings](../services/core/deploy/codex/README.md#docker-sandbox-settings) | [Nodes](getting-started/nodes.md) | +| Docker (node) | [`sandbox/docker`](../services/core/internal/sandbox/docker) | Node proxy in [`sandbox/node`](../services/core/internal/sandbox/node) | [Docker adapter](#docker-adapter) | | microsandbox (node) | [`sandbox/microsandbox`](../services/core/internal/sandbox/microsandbox) | [`tools/microsandbox-provider`](../services/core/tools/microsandbox-provider/README.md) | [Nodes](getting-started/nodes.md) | | E2B (direct) | [`sandbox/e2b`](../services/core/internal/sandbox/e2b) | [`tools/e2b-provider`](../services/core/tools/e2b-provider/README.md) | [Sandbox deployment](../contracts/agents-api/sandbox-deployment.md#e2b-configuration); application-managed templates in [`deploy/e2b`](../services/core/deploy/e2b/README.md) | + +## Docker adapter + +The Docker Sandbox Provider ([`sandbox/docker`](../services/core/internal/sandbox/docker)) runs every Runtime image, whichever Harness it serves, with the same container settings ([`container_options.go`](../services/core/internal/sandbox/docker/container_options.go)): + +- user 1000:1000, read-only root filesystem, all capabilities dropped, `no-new-privileges`, the [seccomp profile](#seccomp-profile) and AppArmor `unconfined`; +- the node’s configured network and extra hosts ([node configuration](configuration.md#docker-node-configuration)); +- CPU and memory from the deployment specification, a 128-process limit and a 128 MiB `/tmp` tmpfs; +- two named volumes labelled with the installation, tenant, Environment and allocation: `-home` at `/home` and `-environment` at `/environment`, whose `workspace` subdirectory is also mounted at `/workspace`. The Docker Engine must support volume subpath mounts; +- with the configured `nested_sandbox` option, Docker's `/proc` masks are lifted (`/sys/firmware` and `/sys/devices/virtual/powercap` stay masked) and the container runs an init process. + +Create refuses to reuse retained volumes that have no container. It copies the [Runtime bootstrap](runtime-bootstrap.md) file to `/home/runtime/runtime-bootstrap.json` (mode 0600, UID 1000) and the `/environment` workspace, staging, initialization and package directories into the container, then starts `oac-daemon connect --profile default --bootstrap-file /home/runtime/runtime-bootstrap.json`. When the created container does not have the configured CPU, memory and exact image, Create returns the error with `CreateSettled`. Docker has no lease, so Renew only reads the container state. Kill checks the ownership labels of the container and both volumes before removing any of them, then confirms that all three are gone. + +The node uses the explicit Unix socket in its [provider configuration](configuration.md#docker-node-configuration) and ignores `DOCKER_HOST`. No Docker socket, host home or Core credential is mounted into a Runtime. + +### Seccomp profile + +[`seccomp.json`](../services/core/deploy/codex/seccomp.json) is the Moby default profile at [revision 65adc7e](https://github.com/moby/profiles/blob/65adc7e022c97f55e45c054ff012988027733b87/seccomp/default.json) (Apache-2.0, see [seccomp.LICENSE](../services/core/deploy/codex/seccomp.LICENSE); upstream file SHA-256 `785b2429264afba4d594320337cb17f144f3c7d51585f9805eef72e28f4f9334`) with one appended rule that allows `clone`, `unshare`, `setns`, `mount`, `umount2` and `pivot_root`. The distribution ships this file to every Docker node as `runtime/seccomp.json`. diff --git a/services/core/deploy/claude/README.md b/services/core/deploy/claude/README.md index 797f52750..327af0f16 100644 --- a/services/core/deploy/claude/README.md +++ b/services/core/deploy/claude/README.md @@ -2,7 +2,7 @@ The Claude adapter runs Claude Code through the pinned Claude Agent SDK. The SDK owns the model and tool loop. Two parts make up the adapter: the private TypeScript bridge in [`packages/claude-sdk-adapter`](../../../../packages/claude-sdk-adapter/README.md), which owns the bridge protocol and native SDK configuration, and the Go adapter in [`agent/claudesdk`](../../../../apps/daemon/internal/agent/claudesdk), which owns the bridge process. This page holds the Runtime-level rules and the Claude Runtime image. [Harness onboarding](../../../../contracts/agents-api/harness-onboarding.md) owns the obligations shared by all adapters. -Native tools run with the daemon user's permissions; the outer sandbox provides isolation ([Runtime and outer isolation](../../../../docs/design-principles.md#runtime-and-outer-isolation)). +Native tools run with the daemon user's permissions; the outer sandbox provides isolation ([Runtime and outer isolation](../../../../docs/concepts.md#runtime-and-outer-isolation)). ## Native pin and readiness @@ -46,4 +46,4 @@ The bridge ([`native_failure.ts`](../../../../packages/claude-sdk-adapter/src/na | Environment | `OAC_RUNTIME_HOME=/home/runtime/.oac`, `OAC_RUNTIME_CLAUDE_SDK_NODE=/usr/local/bin/node`, `OAC_RUNTIME_CLAUDE_SDK_ENTRYPOINT=/opt/claude-sdk/dist/main.js`, `OAC_RUNTIME_WORKSPACE=/environment/workspace`, `OAC_RUNTIME_INITIALIZATION_DIRECTORY=/environment/initialization`, `OAC_RUNTIME_PACKAGE_DIRECTORY=/environment/packages` | | Entry point | `oac-daemon connect --profile default`, working directory `/environment/workspace` | -The build runs the bundle's `runtime_check.js` against its entry point. The distribution copies `/opt/claude-sdk` into the combined Runtime image. Sandboxes run the image with the [Docker sandbox settings](../codex/README.md#docker-sandbox-settings). +The build runs the bundle's `runtime_check.js` against its entry point. The distribution copies `/opt/claude-sdk` into the combined Runtime image. Sandboxes run the image with the [Docker sandbox settings](../../../../docs/sandbox-provider.md#docker-adapter). diff --git a/services/core/deploy/codex/README.md b/services/core/deploy/codex/README.md index b4044e418..61cb9bc9c 100644 --- a/services/core/deploy/codex/README.md +++ b/services/core/deploy/codex/README.md @@ -2,7 +2,7 @@ The Codex adapter ([`agent/codex`](../../../../apps/daemon/internal/agent/codex)) runs the native Codex CLI through its app-server protocol inside the daemon. This page holds the Codex-specific adapter rules, the Codex Runtime image and the Docker sandbox settings that every Docker Runtime uses. [Harness onboarding](../../../../contracts/agents-api/harness-onboarding.md) owns the obligations shared by all adapters. -Native tools run with the daemon user's permissions; the outer sandbox provides isolation ([Runtime and outer isolation](../../../../docs/design-principles.md#runtime-and-outer-isolation)). +Native tools run with the daemon user's permissions; the outer sandbox provides isolation ([Runtime and outer isolation](../../../../docs/concepts.md#runtime-and-outer-isolation)). ## Native pin @@ -71,20 +71,4 @@ Every other variant stays unclassified. The build fails unless `codex --version` reports the pinned version. The image holds no credentials, workspace data or product software. The distribution copies the Codex executable and resources into the combined Runtime image; see the [maintainer guide](../../../../docs/maintainers.md#runtime-images-and-helpers). -## Docker sandbox settings - -The Docker Sandbox Provider ([`sandbox/docker`](../../../../services/core/internal/sandbox/docker)) runs every Runtime image, whichever Harness it serves, with the same container settings ([`container_options.go`](../../../../services/core/internal/sandbox/docker/container_options.go)): - -- user 1000:1000, read-only root filesystem, all capabilities dropped, `no-new-privileges`, this directory's `seccomp.json` and AppArmor `unconfined`; -- the Docker network from the node's provider configuration (`oac-node-` from the node installer), plus any `extra_hosts` there; -- CPU and memory from the deployment specification, a 128-process limit and a 128 MiB `/tmp` tmpfs; -- two named volumes labelled with the installation, tenant, Environment and allocation: `-home` at `/home` and `-environment` at `/environment`, whose `workspace` subdirectory is also mounted at `/workspace`. The Docker Engine must support volume subpath mounts; -- with `nested_sandbox`, which the node installer sets, Docker's `/proc` masks are lifted (`/sys/firmware` and `/sys/devices/virtual/powercap` stay masked) and the container runs an init process. - -Create refuses to reuse retained volumes that have no container. It copies the [Runtime bootstrap](../../../../docs/runtime-bootstrap.md) file to `/home/runtime/runtime-bootstrap.json` (mode 0600, UID 1000) and the `/environment` workspace, staging, initialization and package directories into the container, then starts `oac-daemon connect --profile default --bootstrap-file /home/runtime/runtime-bootstrap.json`. When the created container does not have the configured CPU, memory and exact image, Create returns the error with `CreateSettled`. Docker has no lease, so Renew only reads the container state. Kill checks the ownership labels of the container and both volumes before removing any of them, then confirms that all three are gone. - -The node uses the explicit Unix socket in its provider configuration (`unix:///var/run/docker.sock` from the node installer) and ignores `DOCKER_HOST`. No Docker socket, host home or Core credential is mounted into a Runtime. - -### Seccomp profile - -`seccomp.json` is the Moby default profile at [revision 65adc7e](https://github.com/moby/profiles/blob/65adc7e022c97f55e45c054ff012988027733b87/seccomp/default.json) (Apache-2.0, see `seccomp.LICENSE`; upstream file SHA-256 `785b2429264afba4d594320337cb17f144f3c7d51585f9805eef72e28f4f9334`) with one appended rule that allows `clone`, `unshare`, `setns`, `mount`, `umount2` and `pivot_root`. The distribution ships this file to every Docker node as `runtime/seccomp.json`. +The [Docker adapter](../../../../docs/sandbox-provider.md#docker-adapter) owns the shared container lifecycle and isolation settings. diff --git a/services/core/deploy/e2b/README.md b/services/core/deploy/e2b/README.md index aadf2393c..0fc17bf7f 100644 --- a/services/core/deploy/e2b/README.md +++ b/services/core/deploy/e2b/README.md @@ -82,7 +82,7 @@ Neither record proves enrollment, native readiness or a successful Turn; check t `init.py` runs once as root. It restores the ownership and modes that E2B finalization changes under `/usr/local` and on `envd`, `/etc/inittab` and `/etc/init.d/rcS`, locks E2B's passwordless `user` account, checks that the image environment is not already bound to an Environment or Session and bind-mounts `/environment/workspace` at `/workspace`. It writes the executor key to `/home/runtime/.oac/daemon/executor-key.json` (mode 0600, owned by UID 1000), deletes the startup input and starts `oac-daemon connect --profile default --remote … --environment-id … --credential-file …` as UID/GID 1000. No credential enters the daemon's arguments or inherited environment. The daemon owns enrollment and the local binding. E2B clears `/run` at boot, so the records live under `/root/.oac/e2b`. -The E2B VM is the isolation boundary; tools have UID 1000's access to Runtime state ([Runtime and outer isolation](../../../../docs/design-principles.md#runtime-and-outer-isolation)). +The E2B VM is the isolation boundary; tools have UID 1000's access to Runtime state ([Runtime and outer isolation](../../../../docs/concepts.md#runtime-and-outer-isolation)). ## Tests diff --git a/services/core/deploy/mcode/README.md b/services/core/deploy/mcode/README.md index 42e784646..eed55d773 100644 --- a/services/core/deploy/mcode/README.md +++ b/services/core/deploy/mcode/README.md @@ -2,7 +2,7 @@ The MiniMax Code adapter ([`agent/mcode`](../../../../apps/daemon/internal/agent/mcode)) runs the native MiniMax Code CLI over ACP inside the daemon. MiniMax Code keeps its own ACP Session, model loop and history. The companion package [`packages/mcode-harness`](../../../../packages/mcode-harness/README.md) owns the workspace tool bridge, the native patch and the Subagent history reader. This page holds the Runtime-level adapter rules and the MiniMax Code Runtime image. [Harness onboarding](../../../../contracts/agents-api/harness-onboarding.md) owns the obligations shared by all adapters. -Native tools run with the daemon user's permissions; the outer sandbox provides isolation ([Runtime and outer isolation](../../../../docs/design-principles.md#runtime-and-outer-isolation)). +Native tools run with the daemon user's permissions; the outer sandbox provides isolation ([Runtime and outer isolation](../../../../docs/concepts.md#runtime-and-outer-isolation)). ## Native pin and readiness @@ -50,4 +50,4 @@ In the workspace profile, the frozen installation's Skills are linked into the S | Environment | `OAC_RUNTIME_HOME=/home/runtime/.oac`, `OAC_RUNTIME_MCODE_NODE`, `OAC_RUNTIME_MCODE_BIN`, `OAC_RUNTIME_MCODE_WORKSPACE_BRIDGE`, `OAC_RUNTIME_MCODE_AGENTS_API=1`, `OAC_RUNTIME_WORKSPACE=/environment/workspace`, `OAC_RUNTIME_INITIALIZATION_DIRECTORY=/environment/initialization`, `OAC_RUNTIME_PACKAGE_DIRECTORY=/environment/packages` | | Entry point | `oac-daemon connect --profile default`, working directory `/environment/workspace` | -The build runs the companion's `check.mjs` and the native `--version`. The combined Runtime image uses this image as its base. Sandboxes run it with the [Docker sandbox settings](../codex/README.md#docker-sandbox-settings). +The build runs the companion's `check.mjs` and the native `--version`. The combined Runtime image uses this image as its base. Sandboxes run it with the [Docker sandbox settings](../../../../docs/sandbox-provider.md#docker-adapter). From 1b1e3f225383e7eef016c83262690c5d25004814 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:26:27 +0000 Subject: [PATCH 6/7] docs: remove remaining prose hard wraps without changing rendering --- apps/web/.impeccable/surfaces/src-app-tsx.md | 11 +- example/parsar/README.md | 167 ++++--------------- 2 files changed, 32 insertions(+), 146 deletions(-) diff --git a/apps/web/.impeccable/surfaces/src-app-tsx.md b/apps/web/.impeccable/surfaces/src-app-tsx.md index 2c5bee4f0..c5092f7ad 100644 --- a/apps/web/.impeccable/surfaces/src-app-tsx.md +++ b/apps/web/.impeccable/surfaces/src-app-tsx.md @@ -7,17 +7,10 @@ related_targets: ["src/ConsoleApp.tsx"] # Administrator console (operate) -Scope: the signed-in console shell and every page behind it, including Getting started on the Overview and the optional console tour. Visitor mode: Operate. -Audience: the administrator of one OpenAgentCore deployment. Task: judge health, capacity, usage and failures; inspect and delete project assets; manage projects, keys, nodes and each harness's default model. -Constraints: Web API only (`/core/v1`); missing data stays visibly missing; no small print, explanations live in help tips; API terms stay English in Chinese copy; zh-CN and English, light and dark. +Scope: the signed-in console shell and every page behind it, including Getting started on the Overview and the optional console tour. Visitor mode: Operate. Audience: the administrator of one OpenAgentCore deployment. Task: judge health, capacity, usage and failures; inspect and delete project assets; manage projects, keys, nodes and each harness's default model. Constraints: Web API only (`/core/v1`); missing data stays visibly missing; no small print, explanations live in help tips; API terms stay English in Chinese copy; zh-CN and English, light and dark. Information architecture: Monitor (Overview, Core metrics, Agent metrics, Sandbox metrics, Session log) · Resources (Agents, Environment templates, Skills, Files, Vaults) · Platform (Projects and keys, Nodes, System). ## Direction contract -THESIS: One calm instrument panel for a whole deployment; every screen speaks one component language so the administrator reads state, not layout. Refuses the assembled dashboard of mismatched widgets and loading spinners. -OWN-WORLD: Beautiful UI's foundation: cool near-white canvas, white cards drawn by a hairline ring, neutral ink ramp, 8px-radius buttons (ink primary; only status badges are pills), Inter with CJK system fallback, tabular numerals, semantic tints as condiment; Parsar indigo as the only accent, for selection, links and data. -STORY: The administrator lands on health, sees what needs attention, drills into a project, Session or node, and acts (delete, issue, revoke) without waiting on a spinner. -FIRST VIEWPORT: Page header with title, filters and refresh on one line; KPI strip; the page's primary card (chart grid, table or topology); nothing above the fold is a loader. -FORM: User-pinned world (Beautiful UI + Parsar indigo, 2026-09-24); concept roll skipped because a user-pinned direction beats the roll. -FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, DESIGN.md, and every shipping raster carrying its provenance +THESIS: One calm instrument panel for a whole deployment; every screen speaks one component language so the administrator reads state, not layout. Refuses the assembled dashboard of mismatched widgets and loading spinners. OWN-WORLD: Beautiful UI's foundation: cool near-white canvas, white cards drawn by a hairline ring, neutral ink ramp, 8px-radius buttons (ink primary; only status badges are pills), Inter with CJK system fallback, tabular numerals, semantic tints as condiment; Parsar indigo as the only accent, for selection, links and data. STORY: The administrator lands on health, sees what needs attention, drills into a project, Session or node, and acts (delete, issue, revoke) without waiting on a spinner. FIRST VIEWPORT: Page header with title, filters and refresh on one line; KPI strip; the page's primary card (chart grid, table or topology); nothing above the fold is a loader. FORM: User-pinned world (Beautiful UI + Parsar indigo, 2026-09-24); concept roll skipped because a user-pinned direction beats the roll. FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, DESIGN.md, and every shipping raster carrying its provenance diff --git a/example/parsar/README.md b/example/parsar/README.md index 825e739f5..318bdac4a 100644 --- a/example/parsar/README.md +++ b/example/parsar/README.md @@ -1,15 +1,10 @@ # Parsar Agent workbench -An independently started small application on OpenAgentCore. Manage models, -Skills, HTTP MCP services and runtime configurations; compose reusable Agent -configurations and start independent Sessions. Continue the same Session to keep -its history and live workspace. There is no task layer or shared workspace. +An independently started small application on OpenAgentCore. Manage models, Skills, HTTP MCP services and runtime configurations; compose reusable Agent configurations and start independent Sessions. Continue the same Session to keep its history and live workspace. There is no task layer or shared workspace. ## Run -Use Node 22.13+ (for built-in SQLite) and pnpm 10.30.3. Configure -[Core](../../docs/getting-started/install.md), a deployment model/provider, and a -Project API key. Store secrets in a private environment file outside the checkout: +Use Node 22.13+ (for built-in SQLite) and pnpm 10.30.3. Configure [Core](../../docs/getting-started/install.md), a deployment model/provider, and a Project API key. Store secrets in a private environment file outside the checkout: ```sh export OAC_EXAMPLE_CORE_URL='http://127.0.0.1:8091' @@ -18,109 +13,33 @@ pnpm install --frozen-lockfile pnpm --filter @oac/parsar-example dev ``` -Open http://127.0.0.1:18180. The Core URL is an origin without `/v1`; -remote origins require HTTPS. `OAC_EXAMPLE_PORT` changes the local port. -For a built version, run `pnpm --filter @oac/parsar-example build` and then -`pnpm --filter @oac/parsar-example start`. +Open http://127.0.0.1:18180. The Core URL is an origin without `/v1`; remote origins require HTTPS. `OAC_EXAMPLE_PORT` changes the local port. For a built version, run `pnpm --filter @oac/parsar-example build` and then `pnpm --filter @oac/parsar-example start`. ## Main flow -1. **Models:** enter a Provider name, Base URL and API key, then fetch its - `GET /v1/models` list. Select models with checkboxes or add custom model IDs, - then save the Provider and selected models together. The dialog shows discovered - and selected counts. For manual entry, skip discovery. No default group is - created. Keys are stored in the local restricted SQLite file and never returned - to the browser; leaving the key blank while editing preserves it. Discovery - sends only that Provider's key and does not follow redirects. The list expects - the OpenAI-shaped `data: [{id: "..."}]` response. Discovery failures leave manual - entry available. Codex and Claude Code workspace Sessions pass the selected Provider URL/key - explicitly to Core, using the harness protocol. These Sessions require an HTTPS - Base URL and API key. Text-only Sessions and hosted MiniMax Code use Core's - deployment connection; the creation dialog states that their Provider is only - a catalog group. The example does not yet expose MiniMax Code's required token - limits. -2. **Skills:** create a SKILL.md resource or upload a ZIP. Inspect versions, - upload a new version, and choose the default. Core validates and stores bundles. -3. **MCP:** save anonymous HTTPS endpoints and bind them to Agents. Hosted - Sessions install an inline environment Plugin; text-only Sessions use Core's - service-origin MCP. Hosted HTTP MCP supports Claude Code and Codex, not MiniMax - Code. Authentication, Vault management and OAuth setup are not included. -4. **Runtimes:** choose a Core-managed sandbox, text-only environment, or user - machine. User machines select Linux/macOS/Windows and an existing absolute - workspace path, plus an optional local capability directory. Each Session gets - its own daemon installation and credential; choosing the same workspace path - shares the host's files, so use distinct paths for isolated work. - These are placement configurations, not online machine identities. Machine - enrollment, fixed-node routing and self-hosted registration are omitted. -5. **Agents:** combine a model, harness, instructions, Skills and MCP services. - Create, copy and edit configurations without allocating a runtime. -6. **Sessions:** open an Agent, choose a runtime and send the first message. - Read streaming replies and tool activity, continue the conversation, cancel a running turn and reopen - history. Unsupported Skill/MCP/runtime combinations are explained before creation. - The Session's **Files** dialog uploads one file at a time (up to 5 MiB) through - Core's public Environment Files API while idle. Each upload gets a unique path - under `/workspace/inputs`; a path relative to the working directory is inserted into the message draft, - not sent automatically. Unsent drafts, including uploaded file paths, survive - reloads and navigation in the same browser tab and remain scoped to the Session. This keeps the API's `/workspace` alias distinct from - the physical user-machine directory. Ask the Agent to save generated files - under `./outputs`; - published Artifacts can be paged and downloaded from the same dialog, even when - the live workspace is unavailable. Downloads remain binary; errors stay in the - dialog. Text-only Sessions have no file actions. - Each hosted Session gets its own workspace; text-only has no workspace. - -Agent edits and catalog updates apply to future Sessions. Core freezes existing -Session configuration, including resolved Skill versions. Continuing a Session -retains history and its workspace while the sandbox exists; archiving/replacing a -sandbox is not a persistence guarantee. Saving configuration alone does not verify -model availability or MCP connectivity. Skills require a hosted runtime. +1. **Models:** enter a Provider name, Base URL and API key, then fetch its `GET /v1/models` list. Select models with checkboxes or add custom model IDs, then save the Provider and selected models together. The dialog shows discovered and selected counts. For manual entry, skip discovery. No default group is created. Keys are stored in the local restricted SQLite file and never returned to the browser; leaving the key blank while editing preserves it. Discovery sends only that Provider's key and does not follow redirects. The list expects the OpenAI-shaped `data: [{id: "..."}]` response. Discovery failures leave manual entry available. Codex and Claude Code workspace Sessions pass the selected Provider URL/key explicitly to Core, using the harness protocol. These Sessions require an HTTPS Base URL and API key. Text-only Sessions and hosted MiniMax Code use Core's deployment connection; the creation dialog states that their Provider is only a catalog group. The example does not yet expose MiniMax Code's required token limits. +2. **Skills:** create a SKILL.md resource or upload a ZIP. Inspect versions, upload a new version, and choose the default. Core validates and stores bundles. +3. **MCP:** save anonymous HTTPS endpoints and bind them to Agents. Hosted Sessions install an inline environment Plugin; text-only Sessions use Core's service-origin MCP. Hosted HTTP MCP supports Claude Code and Codex, not MiniMax Code. Authentication, Vault management and OAuth setup are not included. +4. **Runtimes:** choose a Core-managed sandbox, text-only environment, or user machine. User machines select Linux/macOS/Windows and an existing absolute workspace path, plus an optional local capability directory. Each Session gets its own daemon installation and credential; choosing the same workspace path shares the host's files, so use distinct paths for isolated work. These are placement configurations, not online machine identities. Machine enrollment, fixed-node routing and self-hosted registration are omitted. +5. **Agents:** combine a model, harness, instructions, Skills and MCP services. Create, copy and edit configurations without allocating a runtime. +6. **Sessions:** open an Agent, choose a runtime and send the first message. Read streaming replies and tool activity, continue the conversation, cancel a running turn and reopen history. Unsupported Skill/MCP/runtime combinations are explained before creation. The Session's **Files** dialog uploads one file at a time (up to 5 MiB) through Core's public Environment Files API while idle. Each upload gets a unique path under `/workspace/inputs`; a path relative to the working directory is inserted into the message draft, not sent automatically. Unsent drafts, including uploaded file paths, survive reloads and navigation in the same browser tab and remain scoped to the Session. This keeps the API's `/workspace` alias distinct from the physical user-machine directory. Ask the Agent to save generated files under `./outputs`; published Artifacts can be paged and downloaded from the same dialog, even when the live workspace is unavailable. Downloads remain binary; errors stay in the dialog. Text-only Sessions have no file actions. Each hosted Session gets its own workspace; text-only has no workspace. + +Agent edits and catalog updates apply to future Sessions. Core freezes existing Session configuration, including resolved Skill versions. Continuing a Session retains history and its workspace while the sandbox exists; archiving/replacing a sandbox is not a persistence guarantee. Saving configuration alone does not verify model availability or MCP connectivity. Skills require a hosted runtime. ## Ownership and storage -The loopback Node server has two small responsibilities: a fixed allowlist proxy -for public Core resources, and `/app/` CRUD for product-owned configuration. One -SQLite table stores typed JSON records. There is no ORM, background scheduler, -execution database. - -SQLite files live in `~/.oac/data/parsar-example/`. Set the absolute -`OAC_EXAMPLE_DATA_DIR` to relocate them. A hash of the Core origin and Project key -selects the file; changing either selects a different local catalog. Back up the -SQLite file with the server stopped. The Core Project key is not stored in it. Provider keys are stored there. Builds and caches -use `${OAC_DEV_HOME:-$HOME/.oac}`. - -Use one server process and a dedicated Project for this local single-user example. -The server rejects cross-origin writes and keeps the Project key out of browser -responses. Session creation freezes a pending request in SQLite before calling Core, and uses -the local Session ID as its idempotency key. An uncertain response can be recovered -from the Agent's Session list, including after a server restart. Successful creation -leaves only the Core Session reference and local title/Agent/runtime relationship; -Core owns messages, turns and execution status. The browser consumes public SSE -text deltas through a non-buffering proxy, reconnects after interruption, and -reconciles with durable history to avoid duplicate final replies. Each send records -request-return latency and first nonempty text-delta latency from browser request -start. These independent observations remain in sessionStorage across reloads; -missing observations are shown as a dash rather than inferred from history. Definite validation rejection -removes the pending request so it can be corrected. Use one server process. -Deleting a local resource is blocked while another local record references it; -Session deletion/archival is outside this example. Skill deletion is a separate -explicit Core operation. Earlier templates and instances become Agent configs on -startup; they are never presented as actual Sessions. +The loopback Node server has two small responsibilities: a fixed allowlist proxy for public Core resources, and `/app/` CRUD for product-owned configuration. One SQLite table stores typed JSON records. There is no ORM, background scheduler, execution database. + +SQLite files live in `~/.oac/data/parsar-example/`. Set the absolute `OAC_EXAMPLE_DATA_DIR` to relocate them. A hash of the Core origin and Project key selects the file; changing either selects a different local catalog. Back up the SQLite file with the server stopped. The Core Project key is not stored in it. Provider keys are stored there. Builds and caches use `${OAC_DEV_HOME:-$HOME/.oac}`. + +Use one server process and a dedicated Project for this local single-user example. The server rejects cross-origin writes and keeps the Project key out of browser responses. Session creation freezes a pending request in SQLite before calling Core, and uses the local Session ID as its idempotency key. An uncertain response can be recovered from the Agent's Session list, including after a server restart. Successful creation leaves only the Core Session reference and local title/Agent/runtime relationship; Core owns messages, turns and execution status. The browser consumes public SSE text deltas through a non-buffering proxy, reconnects after interruption, and reconciles with durable history to avoid duplicate final replies. Each send records request-return latency and first nonempty text-delta latency from browser request start. These independent observations remain in sessionStorage across reloads; missing observations are shown as a dash rather than inferred from history. Definite validation rejection removes the pending request so it can be corrected. Use one server process. Deleting a local resource is blocked while another local record references it; Session deletion/archival is outside this example. Skill deletion is a separate explicit Core operation. Earlier templates and instances become Agent configs on startup; they are never presented as actual Sessions. A few more implementation details: -- **Providers and models** are saved together in one SQLite transaction. Editing - reads a Provider and its models as one snapshot; changing a model advances the - Provider's revision. -- **Browser calls** use `OpenAIAgentsClient`, with a small public HTTP reader for - Artifacts (not yet exposed by that client); only Session creation goes through a - small server adapter. Closing the browser aborts the upstream stream, never the - running Session. -- **Workspaces:** hosted Sessions each get their own. User-machine Sessions use the - selected host directory, so the same path means shared files. -- **Skills on a user machine** come only from local capability directories in this - example; it rejects Agents bound to managed Skills instead of ignoring them. Core - itself can deliver managed Skills to user machines through - `x_agents_core.environment`. +- **Providers and models** are saved together in one SQLite transaction. Editing reads a Provider and its models as one snapshot; changing a model advances the Provider's revision. +- **Browser calls** use `OpenAIAgentsClient`, with a small public HTTP reader for Artifacts (not yet exposed by that client); only Session creation goes through a small server adapter. Closing the browser aborts the upstream stream, never the running Session. +- **Workspaces:** hosted Sessions each get their own. User-machine Sessions use the selected host directory, so the same path means shared files. +- **Skills on a user machine** come only from local capability directories in this example; it rejects Agents bound to managed Skills instead of ignoring them. Core itself can deliver managed Skills to user machines through `x_agents_core.environment`. ## Validation @@ -129,16 +48,9 @@ make check-example make check ``` -The example gate runs TypeScript, proxy and SQLite persistence/binding tests, -a production build and browser acceptance. Install Chrome with -`pnpm exec playwright install chrome` if necessary. Browser fixtures use -ports 18180/18181 and isolated SQLite data under `~/.oac/tests/parsar-example/`. -They verify Provider groups and model selection, live text before durable completion, -resource management, multiple Sessions, continuation, cancellation, lost-response recovery, -Skill versions and mobile/help behavior. Synthetic fixtures are not model execution. +The example gate runs TypeScript, proxy and SQLite persistence/binding tests, a production build and browser acceptance. Install Chrome with `pnpm exec playwright install chrome` if necessary. Browser fixtures use ports 18180/18181 and isolated SQLite data under `~/.oac/tests/parsar-example/`. They verify Provider groups and model selection, live text before durable completion, resource management, multiple Sessions, continuation, cancellation, lost-response recovery, Skill versions and mobile/help behavior. Synthetic fixtures are not model execution. -The opt-in live browser probe requires an already started example backed by an -isolated real Project: +The opt-in live browser probe requires an already started example backed by an isolated real Project: ```sh OAC_EXAMPLE_LIVE_URL=http://127.0.0.1:18180 \ @@ -146,33 +58,14 @@ OAC_EXAMPLE_LIVE_MODEL='' \ pnpm --filter @oac/parsar-example test:live ``` -It leaves sample resources for inspection and executes the configured model. It -checks Skill/Plugin installation, same-Session file reuse, and workspace isolation -between two Sessions. It asks the model to call DeepWiki; inspect the recorded -tool activity to distinguish a successful call from an attempted call. +It leaves sample resources for inspection and executes the configured model. It checks Skill/Plugin installation, same-Session file reuse, and workspace isolation between two Sessions. It asks the model to call DeepWiki; inspect the recorded tool activity to distinguish a successful call from an attempted call. ## Connect a user machine -Create a user-machine runtime and start a Session with an Agent using Codex or -Claude Code. No initial Turn is sent. Open **Connect user machine** and run the -Core-provided command on the target host. The installer downloads the matching -native distribution, installs the selected harness and starts the connection. -Windows Claude Code also requires Git Bash. The page reads Core's public Environment -status and enables sending after it reports connected. The example backend does -not need or accept the administrator Core key. Commands carry temporary -Environment-scoped authorization; do not share them. Session refresh renews them. - -The selected model Provider needs an HTTPS Base URL and API key. Its protocol is -Responses for Codex and Anthropic for Claude Code. Core freezes and delivers the -configuration to the enrolled executor. Local pending creation requests contain -that configuration but browser Session responses omit the entire pending request. - -Self-hosted capability sources are local directories under the current Core API. -Managed Skill bindings fail explicitly; configure local Skills/Plugins in the -runtime's capability directory before connecting. Bound HTTP MCP services also -fail explicitly for self-hosted Sessions; configure them in local Plugins instead. MiniMax Code self-hosted configuration is not -included in this example because its required token limits are not exposed. - -The daemon runs with the starting user's permissions and adds no sandbox. Runtime -home is separate per Session; stopping it preserves local files. Credential -rotation and revocation remain Core console operations. Reuse the original installation directory when reconnecting. +Create a user-machine runtime and start a Session with an Agent using Codex or Claude Code. No initial Turn is sent. Open **Connect user machine** and run the Core-provided command on the target host. The installer downloads the matching native distribution, installs the selected harness and starts the connection. Windows Claude Code also requires Git Bash. The page reads Core's public Environment status and enables sending after it reports connected. The example backend does not need or accept the administrator Core key. Commands carry temporary Environment-scoped authorization; do not share them. Session refresh renews them. + +The selected model Provider needs an HTTPS Base URL and API key. Its protocol is Responses for Codex and Anthropic for Claude Code. Core freezes and delivers the configuration to the enrolled executor. Local pending creation requests contain that configuration but browser Session responses omit the entire pending request. + +Self-hosted capability sources are local directories under the current Core API. Managed Skill bindings fail explicitly; configure local Skills/Plugins in the runtime's capability directory before connecting. Bound HTTP MCP services also fail explicitly for self-hosted Sessions; configure them in local Plugins instead. MiniMax Code self-hosted configuration is not included in this example because its required token limits are not exposed. + +The daemon runs with the starting user's permissions and adds no sandbox. Runtime home is separate per Session; stopping it preserves local files. Credential rotation and revocation remain Core console operations. Reuse the original installation directory when reconnecting. From f99144efde57ed2c6540bf61d79515952cd25313 Mon Sep 17 00:00:00 2001 From: SaladDay <1203511142@qq.com> Date: Wed, 30 Sep 2026 09:28:31 +0000 Subject: [PATCH 7/7] docs: spell out the Core database package path --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index ca559a302..42c7665c5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -58,7 +58,7 @@ For frontend development, run `pnpm dev:web` using the fixture or Core connectio | Location | Responsibility | Read next | | --- | --- | --- | | `services/core/internal/api` | Public, administrator and machine HTTP boundaries | [API index](api/README.md) | -| `services/core/internal/store` and `internal/db` | Core persistence, transactions, queries and migrations | [Service guide](../services/core/README.md#database) | +| `services/core/internal/store` and `services/core/internal/db` | Core persistence, transactions, queries and migrations | [Service guide](../services/core/README.md#database) | | `services/core/internal/execution` | Durable Turn dispatch and scheduling | [Runtime protocol](runtime-protocol.md) | | `services/core/internal/engine` | Pure qualification of harness operations and placements | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) | | `internal/agentdaemon/proto` | Core–Runtime wire types and validators | [Runtime protocol](runtime-protocol.md) |