diff --git a/.gitignore b/.gitignore index 2b3279650..3e8ddbf81 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,3 @@ __pycache__/ /.agents/ /.issue-agent/ /ISSUE_AGENT.md - -# Documentation site build output. -/apps/docs/.next/ -/apps/docs/.source/ -/apps/docs/tsconfig.tsbuildinfo diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2cd9664df..5b9300ef5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ This guide owns how to work in the repository: documentation ownership, the repo | 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](apps/docs/README.md) | +| Documentation website generation | Docs app | ## Repository boundary diff --git a/Makefile b/Makefile index 0fd6cef42..d36c81471 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ SWAG_VERSION ?= v1.16.4 help: @printf '%s\n' 'make build-core Build standalone Core commands' 'make build-daemon Build the execution daemon' 'make check Run Core, persistence and runtime checks' 'See README.md for runtime prerequisites and deployment.' -check: check-harness-catalog check-docs check-names check-distribution check-database check-sqlc check-go check-microsandbox-provider check-core check-claude-sdk check-web check-example check-mcode-harness +check: check-harness-catalog check-names check-distribution check-database check-sqlc check-go check-microsandbox-provider check-core check-claude-sdk check-web check-example check-mcode-harness @printf 'OpenAgentCore checks passed.\n' .PHONY: generate-harness-catalog check-harness-catalog @@ -166,10 +166,6 @@ check-e2b-provider: PYTHONDONTWRITEBYTECODE=1 $${OAC_TEST_E2B_SDK_PYTHON:-python3} -m unittest discover -s services/core/deploy/e2b -p '*_test.py' PYTHONDONTWRITEBYTECODE=1 $${OAC_TEST_E2B_SDK_PYTHON:-python3} -m unittest discover -s services/core/tools/e2b-provider -p '*_test.py' -.PHONY: check-docs -check-docs: node-deps - pnpm check:docs - # These packages are also exercised by check-core in the full gate. .PHONY: check-sandbox-provider-contract check-sandbox-provider-contract: diff --git a/apps/docs/README.md b/apps/docs/README.md deleted file mode 100644 index ab465bf51..000000000 --- a/apps/docs/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# OpenAgentCore documentation site - -A separate Next.js/Fumadocs documentation app. It starts no Core, database or Runtime. - -The application reference reads the upstream-constrained public schema. Administration -and machine references read their own local generated contracts. All three repository -files currently declare Swagger 2.0; rendering supports Swagger 2 and OpenAPI 3. -The documentation projection uses OpenAPI 3.1 null unions (including nullable references -and compositions). Normalization changes documentation servers and bearer presentation, preserving operation -prose, parameters, response schemas and credential boundaries. Examples use a reserved -domain. The reference is read-only and must not collect keys or send execution requests. - -Guides are generated from the canonical repository docs, not maintained as a -second manual. Edit those sources first, register pages in -[guides.json](scripts/guides.json), then regenerate. Source/output hashes fail when -copies drift; operation and route checks detect missing or mixed API surfaces. - -From the repository root: - -```sh -pnpm install --frozen-lockfile -pnpm --dir apps/docs generate -pnpm --dir apps/docs verify -pnpm --dir apps/docs test -pnpm --dir apps/docs typecheck -pnpm --dir apps/docs build -pnpm --dir apps/docs start --port 4275 -``` - -The route verifier uses the declared `js-yaml` dependency and Python standard library -only; no ambient PyYAML installation is required. Python checks honor -`OAC_TEST_OFFICIAL_SDK_PYTHON` when set, otherwise `python3`, and run with `-S` -to keep site packages out of the gate. - -`make check-docs` runs the focused gate and is included in `make check`. After starting -the built site, run `pnpm --dir apps/docs check:site http://127.0.0.1:4275` and inspect -the guides in a browser with `pnpm --dir apps/docs check:browser http://127.0.0.1:4275`. -The check uses installed Playwright Chromium (or `DOCS_BROWSER_EXECUTABLE`), checks -for credential/request controls and external traffic, and accepts only a local origin. -Set `DOCS_SITE_ORIGIN` only when preparing actual publication. -Generation links to the recorded source revision; update that revision after rebasing -onto later canonical guide changes. Never point samples at an actual deployment by default. - -Current supported behavior and acceptance evidence live in the -[contract index](../../contracts/agents-api/README.md). diff --git a/apps/docs/app/[[...slug]]/page.tsx b/apps/docs/app/[[...slug]]/page.tsx deleted file mode 100644 index ce9b7c35f..000000000 --- a/apps/docs/app/[[...slug]]/page.tsx +++ /dev/null @@ -1,63 +0,0 @@ -import type { Metadata } from "next" -import { notFound } from "next/navigation" -import { ImageZoom } from "fumadocs-ui/components/image-zoom" -import defaultMdxComponents from "fumadocs-ui/mdx" -import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/page" -import { APIPage } from "@/components/api-page" -import { absoluteDocsUrl } from "@/lib/site" -import { source } from "@/lib/source" - -function pageSlug(slug?: string[]) { - return slug ?? [] -} - -export default async function DocsPageRoute({ - params, -}: { - params: Promise<{ slug?: string[] }> -}) { - const { slug } = await params - const page = source.getPage(pageSlug(slug)) - if (!page) notFound() - - const MDX = page.data.body - return ( - - {page.data.title} - {page.data.description} - - - - - ) -} - -export function generateStaticParams() { - return source.generateParams() -} - -export async function generateMetadata({ - params, -}: { - params: Promise<{ slug?: string[] }> -}): Promise { - const { slug } = await params - const slugs = pageSlug(slug) - const page = source.getPage(slugs) - if (!page) return {} - return { - title: page.data.title, - description: page.data.description, - alternates: { canonical: absoluteDocsUrl(page.url) }, - } -} diff --git a/apps/docs/app/docs-providers.tsx b/apps/docs/app/docs-providers.tsx deleted file mode 100644 index e70421d8b..000000000 --- a/apps/docs/app/docs-providers.tsx +++ /dev/null @@ -1,17 +0,0 @@ -"use client" - -import Image from "next/image" -import Link from "next/link" -import { useParams, usePathname, useRouter } from "next/navigation" -import { FrameworkProvider, type Framework } from "fumadocs-core/framework" -import { RootProvider } from "fumadocs-ui/provider/base" -import type { ReactNode } from "react" - -export function DocsProviders({ children }: { children: ReactNode }) { - return ( - - {children} - - ) -} diff --git a/apps/docs/app/global.css b/apps/docs/app/global.css deleted file mode 100644 index cc12ffffa..000000000 --- a/apps/docs/app/global.css +++ /dev/null @@ -1,103 +0,0 @@ -@import "tailwindcss"; -@import "fumadocs-ui/css/neutral.css"; -@import "fumadocs-ui/css/preset.css"; -@import "fumadocs-openapi/css/preset.css"; - -:root { - --color-fd-primary: hsl(240 5.9% 10%); -} - -/* Keep the active navigation item readable in dark mode. The neutral theme - defines a light primary color for dark surfaces; this override must be more - specific than the root token declared above. */ -.dark { - --color-fd-primary: hsl(0 0% 98%); - --color-fd-primary-foreground: hsl(240 5.9% 10%); -} - -body { - font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", - "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif; -} - -/* Medium weight maps to regular in common CJK fonts. */ -.prose :where(strong):not(:where(.not-prose, .not-prose *)) { - font-weight: 700; -} - -.prose pre { - min-width: 0; - width: 100%; -} - -/* Code blocks wrap instead of scrolling sideways. */ -.prose pre, -.prose pre code { - white-space: pre-wrap; - overflow-wrap: anywhere; -} - -/* Inline code wraps only when a token cannot fit on a line of its own. - `overflow-wrap: anywhere` also reduces the element's min-content width to - roughly one character, and the automatic table layout then treats a column - as shrinkable to that width: a five-column table collapsed the first column - to 49px and split `environment.type` across five lines. `break-word` breaks - a long token as a last resort without affecting intrinsic sizing, so a - column keeps at least its longest parameter. */ -.prose :not(pre) > code { - white-space: pre-wrap; - overflow-wrap: break-word; -} - -/* Give every table column a readable floor. The minimum content width of a - column with short words is about one character, while a column - holding a parameter such as `OAC_DATABASE_URL` cannot shrink below - that parameter. The automatic layout satisfies the wider columns first and - can crush a short-label column to a few characters per line. Five columns of - 7rem still fit the narrowest content area the layout produces. */ -.prose table :is(th, td) { - min-width: 7rem; -} - -/* Make the page-tree separators read as navigation groups, not page links. */ -#nd-sidebar [data-radix-scroll-area-viewport] p { - width: 100%; - margin-top: 1.25rem; - margin-bottom: 0.5rem; - padding: 0.35rem 0.5rem; - border-bottom: 1px solid var(--color-fd-border); - color: var(--color-fd-muted-foreground); - font-size: 0.7rem; - font-weight: 700; - letter-spacing: 0; - line-height: 1.25rem; -} - -#nd-sidebar [data-radix-scroll-area-viewport] p:first-of-type { - margin-top: 0; -} - -#nd-sidebar [data-radix-scroll-area-viewport] a[href^="/"] { - min-height: 2.25rem; - font-size: 0.875rem; -} - -/* Keep the language menu compact inside the sidebar and on narrow screens. */ -[role="dialog"][data-side] { - width: min(11rem, calc(100vw - 2rem)); - min-width: 0 !important; - /* Radix anchors this bottom-left menu at x=0; keep it off the viewport edge. */ - margin-left: 0.75rem; -} - -[role="dialog"][data-side] button { - width: 100%; -} - -/* Text selection: tint the background with the theme's primary color and keep - the original text color, so contrast is inherited from body text in both - themes. Forcing --color-fd-primary-foreground here previously produced white - text on a mid-gray highlight in light mode. */ -::selection { - background: color-mix(in srgb, var(--color-fd-primary) 22%, transparent); -} diff --git a/apps/docs/app/icon.svg b/apps/docs/app/icon.svg deleted file mode 100644 index dba271faf..000000000 --- a/apps/docs/app/icon.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/apps/docs/app/layout.config.tsx b/apps/docs/app/layout.config.tsx deleted file mode 100644 index 9ba8db958..000000000 --- a/apps/docs/app/layout.config.tsx +++ /dev/null @@ -1,10 +0,0 @@ -import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared" - -export const baseOptions: BaseLayoutProps = { - nav: { - title: <>OpenAgentCore Docs, - }, - searchToggle: { - enabled: false, - }, -} diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx deleted file mode 100644 index a14a4972e..000000000 --- a/apps/docs/app/layout.tsx +++ /dev/null @@ -1,24 +0,0 @@ -import "./global.css" -import type { Metadata } from "next" -import type { ReactNode } from "react" -import { DocsLayout } from "fumadocs-ui/layouts/docs" -import { baseOptions } from "./layout.config" -import { source } from "@/lib/source" -import { DocsProviders } from "./docs-providers" - -export const metadata: Metadata = { - title: { template: "%s | OpenAgentCore Docs", default: "OpenAgentCore Docs" }, - description: "Documentation for OpenAgentCore.", -} - -export default function RootLayout({ children }: { children: ReactNode }) { - return ( - - - - {children} - - - - ) -} diff --git a/apps/docs/app/not-found.tsx b/apps/docs/app/not-found.tsx deleted file mode 100644 index 50fb7d8d0..000000000 --- a/apps/docs/app/not-found.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import Link from "next/link" - -export default function NotFound() { - return ( -
-

Page not found

-

The requested documentation page does not exist.

- Back to the manual -
- ) -} diff --git a/apps/docs/app/sitemap.ts b/apps/docs/app/sitemap.ts deleted file mode 100644 index bb002fb83..000000000 --- a/apps/docs/app/sitemap.ts +++ /dev/null @@ -1,7 +0,0 @@ -import type { MetadataRoute } from "next" -import { absoluteDocsUrl } from "@/lib/site" -import { source } from "@/lib/source" - -export default function sitemap(): MetadataRoute.Sitemap { - return source.getPages().map(page => ({ url: absoluteDocsUrl(page.url) })) -} diff --git a/apps/docs/components/api-page.tsx b/apps/docs/components/api-page.tsx deleted file mode 100644 index 3976f2a65..000000000 --- a/apps/docs/components/api-page.tsx +++ /dev/null @@ -1,13 +0,0 @@ -import { APIPage as OpenAPIPage, type ApiPageProps } from "fumadocs-openapi/ui" -import { loadSurface } from "@/lib/openapi" - -// Registered as `APIPage` for the MDX components map. The generated pages name -// their API surface by id; the contract itself is loaded through the server -// instance so the rendered schema and the generated prose stay in step. -export async function APIPage({ - document, - ...props -}: Omit & { document: string }) { - // References never collect credentials or dispatch requests from the browser. - return -} diff --git a/apps/docs/content/docs/admin-api.mdx b/apps/docs/content/docs/admin-api.mdx deleted file mode 100644 index 5d33fa897..000000000 --- a/apps/docs/content/docs/admin-api.mdx +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: "Core administration API" -description: "Management operations and their server-side credential boundary." ---- - -Core Web is an administrator console over `/core/v1`, authorized by the Core key: -resource inspection, Project and key management, credential issuance, audit, usage -and sandbox operations. It never calls `/v1` or `/api/v1`, and has no Agent -execution, copy or arbitrary asset editing operation. - -Core request failures use the [Core administration error envelope](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md), -including optional typed safe details. Console sign-in endpoints retain their -separate error shape described below. - -## Browser to console - -The browser uses the console's own origin and signs in with the -[Core key](/troubleshooting#core-key): - -| Method and route | Request | Result | -| --- | --- | --- | -| `GET /console/auth` | No body | `200 {"mode":"login"}` or `200 {"mode":"authenticated"}` | -| `POST /console/auth/login` | `Content-Type: application/json`, body `{"core_key":"…"}`; other members are rejected | `200 {"mode":"authenticated"}` and an HttpOnly, SameSite=Strict session cookie (Secure over HTTPS) | -| `POST /console/auth/logout` | No credential payload | `200 {"mode":"login"}`; clears the cookie and the server-side session | -| `GET /console/config` | Signed-in session | `node_installer`, `node_installer_sha256`, `node_artifacts`: the providers (`docker`, `microsandbox`) whose node assets this console holds | - -Sign-in errors use the console's `{"error": "…"}` envelope: 400 for a malformed -body, 401 for a wrong key, 415 for a non-JSON body, 429 with `Retry-After` when -failed attempts are limited or sign-in is busy, and 503 when the console cannot -start a session. The console compares the submitted key with its configured Core -key in constant time and never logs or returns it. Only failed attempts count -toward the limit; the correct key signs in even while failures are limited. The -console refuses to start with a Core key shorter than 32 characters. Sessions live only in the console's memory; a console restart -or Core key rotation requires signing in again. There are no console accounts, -usernames, passwords, account setup or Basic authentication. - -Use same-origin browser requests and cookies. Mutations require the same-origin -request checks; never put the Core key in JavaScript or browser storage. - -### Managed domain setup - -This console-local surface uses the signed-in session and the same-origin checks -above. It forwards to the installation controller, not Core. - -| Method and route | Request | Result | -| --- | --- | --- | -| `GET /console/installation/domain` | No body | Domain setup status | -| `POST /console/installation/domain` | `{"hostname":"core.example.com"}`; optional `confirm_public_url_change` equal to `https://core.example.com` | `202` and the current status; one asynchronous installer operation | - -Status contains `supported`, `state` (`unconfigured`, `checking`, `applying`, -`ready`, `failed`), nullable `public_url`, `target_url` and `message`. External -proxy installations report `supported: false`. A POST with existing address -bindings requires explicit confirmation and otherwise returns `409` with code -`public_url_confirmation_required`. Other rejections include invalid hostnames, -pending configuration edits and another installation operation holding the lock. -Action errors use `{"error":{"code":"…","message":"…"}}`; console authentication -failures retain the sign-in error shape above. - -Poll the same-origin GET while preparing. Applying the change restarts Web and -ends its sign-in sessions; provide a link to the submitted HTTPS origin for a -fresh login. A dropped request or cross-origin browser probe does not prove -success. The [installer contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/deploy/install/README.md#managed-https) owns -certificate verification, locking, retry and rollback. - -## Console to Core - -After sign-in and the same-origin checks, the console server forwards every -`/core/v1/*` request with its private Core key as the Bearer credential; Core -alone decides whether the route exists. It removes browser Authorization and -forwarding-sensitive headers, and sets `X-Core-Console-Actor: console`. Core -records the header as the audit `actor_label`. The label is caller-asserted and -display-only: direct Core key scripts normally send none, which records an empty -label, but could set any value. Never use it for authorization or as proof of -origin. - -Web calls Core only through the typed Core clients in `packages/agents-client`: -[AdminClient](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/packages/agents-client/src/admin-client.ts) (`/core/v1`), -`SandboxAdminClient` (`/core/v1/sandbox`) and `CoreMetricsClient` -(`/core/v1/metrics`). See [the complete administrator reference](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/admin-api.md) -for methods, fields, filters, pagination and response shapes. -Routes below are relative to `/core/v1`: - -| Workflow | Routes | -| --- | --- | -| Projects | `GET/POST /projects`, `POST /projects/{id}`, `POST /projects/{id}/archive` | -| Project keys | `GET/POST /projects/{id}/keys`, `DELETE /projects/{id}/keys/{key_id}` | -| Resource lists/details/deletion | `/projects/{id}/agents`, `/sessions`, `/environment-templates`, `/skills`, `/files`, `/vaults`, including the documented nested reads | -| Asset ownership | `GET /projects/{id}/resource-owners` with batched resource IDs | -| Key operation history | `GET /projects/{id}/write-operations` with key/resource/time filters | -| Executor credentials | `GET/POST /projects/{id}/environments/{environment_id}/executor-credentials`, `DELETE …/executor-credentials/{key_id}` ([contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-executor-credentials.md)) | -| Deployment model configuration | `GET /harnesses`, `GET/PUT/DELETE /harnesses/{harness}/model-configuration`; the key is write-only ([contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/model-execution.md#deployment-defaults)) | -| Usage and health | `GET /summary`, `/sandbox/runtime-observations`, `/metrics` | -| Administrator audit | `GET /audit-log`; deployment-wide entries have `project_id: null` | - -A Project UUID in a management path selects the target; it is not a credential. -API-key plaintext is returned only by successful issuance, so display it once and -never cache it. Reconcile uncertain issuance before explicitly issuing another key. -Deleted/revoked resources retain their audit records. Historical unknown ownership -stays null. Session usage grouped by key belongs to the Session's creation key; -it is operational attribution, not per-key billing. - -## Sandbox administration - -The [deployment configuration contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/sandbox-deployment.md), -[nodes guide](/hosted-providers) -and [generated OpenAPI](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core.openapi.yaml) -define deployment and node operations: - -- `GET/POST/PUT /core/v1/sandbox/deployment` and - `POST/DELETE /core/v1/sandbox/deployment/reset`. -- `GET /core/v1/sandbox/nodes`, `PATCH/DELETE /core/v1/sandbox/nodes/{node_id}`, - and `GET /core/v1/sandbox/nodes/{node_id}/allocations`. -- `POST /core/v1/sandbox/enrollment-tokens` for a one-time node installation command. - Its non-secret `enrollment_id` reappears on the node that command registers. - -PostgreSQL owns one provider, per-sandbox resource specification and immutable -Runtime selection. POST initializes it and PUT updates the same provider; both -require the observed `expected_generation`, including zero at first setup. Requests carry `resources` and, for Docker/microsandbox, -`runtime`; safe responses return `specification` and `specification_digest`. -Response `resources.allocations` and `resources.pending` are cleanup counts, not -CPU, memory or disk settings. E2B accepts a write-only key and exact template build -instead of a node Runtime release, and provisions without a node installation. E2B -may omit `resources` to adopt the validated build's CPU and memory. An E2B-compatible -service may also supply paired `e2b.api_url` and `e2b.domain`; omitted selectors -use official E2B. Responses expose these addresses but never the key, and changing -them requires the same drained maintenance transition as changing the template. -Responses show -the build as read at selection time in `e2b.template_build`. Microsandbox responses -return its idle `suspension` policy; other providers return null. - -Same-team E2B updates apply online after verification. Existing sandboxes retain -their generation and use the committed credential for management; omitting the key -preserves it, while explicitly submitting even the same key verifies a replacement. -Node-provider updates still require zero retained/pending resources and no reset. -Changing backend or E2B team requires explicit durable reset before a new POST. -Auto archives idle/queued/suspended hosted Sessions, waits for started work and -file writes, and escalates at its persisted deadline; force requests cancellation -and verified cleanup. The deployment response supplies the authoritative -`reset.remaining` partition and offline-node subset; Web must not derive either -from independently loaded lists. The separate `rollout.state` describes target -preparation; old-generation resource counts alone do not imply active preparation. -Poll rapidly while reset is active or rollout is preparing. Node `ready_generation` -is a durable serving pin, not proof of current connectivity. Target unknown, failed -or update-required state does not by itself invalidate confirmed old-generation -service; consume Core's connection/provider facts separately. - -Administrators may [archive an individual hosted Session](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/admin-api.md#administrative-session-archive) -at the current generation without reset. History and persisted Files/Artifacts -survive; unpersisted workspace is lost and the original Session cannot resume. -Cancel reset stops further archives, not cleanup already requested. After zero -resources Core clears the selection and advances generation; configure again using -that new generation. Never automatically replay an uncertain write. -Public Environment Templates, the `/v1` contract and -caller-owned `self_hosted` provisioning remain unchanged. - -`GET /api/v1/sandbox-node/configuration` uses an enrollment Bearer token, or a -retained node Bearer credential with `X-OAC-Node-ID`. This read does not consume -enrollment. Retained matching nodes can read their configuration during reset. -Installers must verify the returned generation, specification digest and Runtime -before registration; local files cannot override the saved limits. A mismatch -returns `sandbox_specification_mismatch` without replacing node state. - -Node configuration, enrollment, identity and connection routes live under -`/api/v1/sandbox-node`, beside the daemon's `/api/v1/agent-daemon`. The reverse -proxy sends `/api/v1` directly to Core; the console returns 404 for it and never -forwards machine traffic. These routes use their own credentials, do not inherit a -browser login and gain no management authority. E2B credentials are absent -from node configuration and safe deployment views. - -## Frontend handoff and errors - -Frontend screen implementation is owned by the separate frontend task. The -backend provides the `/core/v1` contract, the typed Core clients and the console -proxy; backend tests do not qualify the screens. - -The console returns 404 for `/v1`, `/api/v1` and old `/console/api-keys` routes, -even with an explicit application or machine Bearer credential. Invalid -Origin/Host requests are rejected; unavailable Core or rejected upstream redirects -return 502. Console authentication uses its own error envelope. Management resource -errors and deletion constraints are documented in the administrator reference and -generated schema; do not interpret every empty or failed read as an absent resource. - -## Core metrics - -`GET /core/v1/metrics?range=1h|6h|24h|7d` returns Core process, execution -queue/slots, PostgreSQL and background-job measurements. It requires the Core key, -rejects arbitrary query filters and never grants -Agent execution access. See the [exact measurement contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-metrics.md) -for complete buckets, null values, units and process-local retention. Frontend -implementation is maintained separately; this backend change does not modify -Agent metrics or the public Agent API. - -## Node host history - -The Core key reads a node and its host history through -`GET /core/v1/sandbox/nodes/{node_id}?range=1h|6h|24h`. See the -[node host history contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/node-host-history.md) -for nullable observations, freshness and aggregation. The node list is unchanged. - -[Repository source](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/api/web-management.md) diff --git a/apps/docs/content/docs/agents-and-tools.mdx b/apps/docs/content/docs/agents-and-tools.mdx deleted file mode 100644 index ef385bdac..000000000 --- a/apps/docs/content/docs/agents-and-tools.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Agents, tools and harnesses" -description: "Native harness tools, shared declarations and the limits of execution support." ---- - -Assessed against Core `206474a4c10901442b1faa094281bfb5559082b5` on 2026-09-22. -The contract remains [OpenAI Python 3.13.0 at `d7c41ef`](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/upstream.json), Beta -`agents=v1`. This matrix records the bounded execution/tools milestone. It does not -establish complete protocol compatibility; the remaining limits below stay open. - -**Implemented** means current source and controlled checks support the operation. -**Qualified** additionally identifies a real public Core/PostgreSQL/daemon/native -model workflow in the evidence register below. **Unsupported** describes a current -admission/native limitation, not a restriction in the official contract. -**Unverified** means evidence does not establish the stated semantics or profile. -Qualification never extends automatically to another model, placement or combination. - -## Operation matrix - -All function rows refer to application-defined functions. Native workspace tools -and Environment Plugin MCP have separate inventories and qualification. - -| Operation | Implemented behavior and real qualification | Unsupported or unverified boundary | -| --- | --- | --- | -| Initial message input, `sessions.create` | String input and ordered user-message arrays share atomic admission. Codex/Claude text and inline image execution: M1/M2; ordinary MiniMax text: M1/P1. [Input contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/message-input.md), [initial parser](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/api/session_initial_input.go). | Whitespace-only text is admitted verbatim for Codex and rejected at admission for Claude SDK and MiniMax Code ([text content](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/message-input.md#text-content)). Empty parts beside text (SES-08) and local size-limit parity need upstream evidence. Inline PNG/JPEG is qualified on `none`, Core-managed Docker `openai_hosted` and `self_hosted`; MiniMax images and remote URLs remain gaps. | -| Prepared and active messages, `sessions.events.create` | Ordered `input_text`/`input_image` arrays retain original content and distinct public user Items. HTTP 202 confirms persistence; native receipts establish application. Initial/prepared/active Docker PNG/JPEG: M2; active PNG on `none`: M1. [Shared admission](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/api/inputs.go). | Codex flattens native messages with blank-line separators. Claude can fold or queue native turns; it does not promise Codex's same-native-turn behavior. Public durability does not prove native consumption. Claude SDK and MiniMax Code reject messages without an image or non-whitespace text at admission (`unsupported_or_invalid_configuration`); Codex delivers them unchanged. | -| Structured output, `agent.text.format` | Save/inherit/freeze `{type:json_schema,schema:...}`. Claude SDK object-root, single Agent, medium verbosity, ordinary functions returning text: S1 (`none`) and S2 (Docker, including prepared/active input and Files/Artifacts), plus [self-hosted execution and cold continuation](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-capabilities-qualification.md). Native final text is retained unchanged; its stream follows the official message sequence with the whole text in one `output_text.delta` ([item serialization](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/history-events-usage.md#item-serialization-2026-09-23)). [Contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/structured-output.md), [profile](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/engine/claude.go). | An explicit non-object root type is a protocol error for every harness ([validation](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/official-semantics-alignment.md#agent-configuration-validation--september-23)). Codex/MiniMax, schemas without an object root, schema numbers changed by binary64, Skills/Plugins, MCP, Subagent and discovery combinations reject execution. No output repair, coercion or extra model loop. Arbitrary schema dialects are unverified. | -| Function configuration, saved/inline Agents | Required name/description/schema; `defer_loading` defaults false. Protocol errors, repeated names and explicit non-object root types reject with the official fields ([validation](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/official-semantics-alignment.md#agent-configuration-validation--september-23)). Saved references resolve into an immutable Session snapshot. Codex/Claude real calls: F1/F2/M2/S1/S2. [Parser](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/api/function_configuration.go), [saved tools](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/api/saved_tools.go). | MiniMax public functions reject. Claude requires an explicit object root. Local nonblank/512-byte name and 64-definition Session bounds are compatibility gaps. Saving configuration alone does not qualify execution. | -| Function-result admission, `events.create` | Required `turn_id`, `call_id`, `success`; optional nullable `error` and `output`. Output is string or ordered text/image content. Scoped atomic batches retain field presence, original content and retry identity in storage; public result Items and events always carry `output` and `error`, null when not submitted ([item serialization](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/history-events-usage.md#item-serialization-2026-09-23)). Same result retries are accepted; changed results and results after cancellation return 409 `conflict_error`, including after terminal state. In the caller's Session, an unknown call or a call of another Turn returns 400 `invalid_request_error` without changing the pending action; missing and foreign Sessions stay 404 ([error rows](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/official-semantics-alignment.md#session-input-conflicts-and-result-targets--september-23)). F1/F2/M2 plus [controlled SDK/raw checks](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/tests/official_function_inputs.py). [Parser](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/api/function_inputs.go), [Store](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/store/function_inputs.go). | Admission is separate from application and public Item publication. Invalid or unqualified content cannot consume a pending call. Core messages omit the call and executor IDs that official messages name; hosted defaults and publication timing remain unverified. | -| Function text results and native application | Codex waits for a matching live root dynamic-tool completion; Claude waits for a matching live root native tool result. Text/error results, retry/conflict, cancellation and cold continuation: F1/F2. [Receipt contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/function-result-images.md). | Transport writes alone do not confirm application. Confirmation is not provider consumption, crash recovery or exactly-once external effects. No automatic result replay. | -| Function image results | Successful ordered inline PNG/JPEG with text, large PNG and image-only JPEG: Codex/Claude `none` F1/F2; Docker M2. Public Items retain submitted bytes. Codex receipt regression: F2. | Claude rejects failed images and remote references before persistence; native resizing may change its image bytes. Self-hosted Claude image results use the same native path; see the current [qualification record](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-capabilities-qualification.md). MiniMax functions remain unqualified. Other Codex image/error/reference combinations cannot be inferred from successful-inline evidence. | -| Deferred function discovery | Type-only `tool_search` plus mixed eager/deferred functions: Claude SDK 0.3.269/native 2.1.269, Kimi K3, single Agent, medium, `none`, text results; text and PNG input D1. Native provider observations establish lazy schema loading for D1. [Self-hosted workspace callback, continuation and cancellation](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-capabilities-qualification.md) use the same native path; they do not add model-request observer evidence. [Contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/tool-search.md). | A repeated `tool_search` is a protocol error. Codex/MiniMax discovery, search-only/missing-search, workspace with Skills/Plugins, MCP, structured-output and Subagent combinations remain gaps. Opaque native policy changes lack a reliable pre-input deferral signal. Saved tools include `tool_search`; the pinned Session response union excludes it. Exact hosted projection is unverified. | -| Explicit disabled search/PTC | Saved and inline `web_search.mode=disabled` and `programmatic_tool_calling.enabled=false`; shared native controls on initial and cold execution. All three harnesses on `none`: P1, including native inventory/control evidence. [Contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/tool-policy.md), [parser](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/api/disabled_tools.go). | Unsupported explicit enablement rejects at Session admission; saved Agents keep every pinned search mode as resource data (TV-05), and Sessions from such Agents reject unless they replace the tools. A repeated `web_search` is a protocol error. Omission retains approved native behavior, which does not establish official default-on PTC parity. Enabled search and default/error parity remain gaps; unrelated native utilities are not implicitly removed. | -| Agent service-origin MCP | Implemented Codex/Claude HTTP `none` profiles, anonymous/static bearer, scoped Vault selection and native `mcp_call` Items. [Configuration and qualification limits](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/README.md#http-mcp-execution), [profiles](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/engine/profile.go). | This closure batch does not requalify MCP/provider combinations. MiniMax, self-hosted/hosted service-origin MCP, OAuth, nonempty inline headers/metadata and other transports reject. Environment origin follows the separate row below. Claude requires a static connected inventory; original MCP-envelope fidelity and continuing server health are unverified. | -| Agent Environment-origin MCP | Public HTTP declarations reuse installed MCP's effective Runtime bindings; attached Vault selection and native observations remain common. [Origin and Harness matrix](/environments-and-files#public-mcp-connection-origin), [real qualification](https://github.com/MiniMax-AI/OpenAgentCore/blob/e974a7f880a2eb799f0dd39e6ba0870462854a53/contracts/agents-api/public-mcp-qualification.md). | Requires a workspace and enabled network. MiniMax rejects every non-null allowlist and required initialization. No service-origin relocation, automatic fallback or credential copy into native profiles. | -| Environment Plugin MCP/native tools | Separate [Docker Plugin transport matrix](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-templates.md#environment-origin-mcp-plugins) and [V1 deployment evidence](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/user-managed-runtime-v1.md). Native tools stay within the existing colocated Runtime. | Plugin MCP is not Agent service-origin MCP or a public function action. No new optional cross-product is qualified here. Native utility inventories need not be identical. | -| Required action: `function_call` | Session GET/list and Session SSE expose persisted `{arguments,call_id,name,turn_id,type}`. Actions remain pending until native application or cancellation/terminal settlement. [Projection](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/store/function_state.go), [confirmation](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/store/function_results.go); real handling F1/F2/M2/S1/S2/D1; explicit client disconnect/query/reconnect: F3. | Function-call history is not pending-state authority. Client reconnect does not replay events or redo external application effects. | -| Required action: `environment_connection` | Offline waiting input exposes `{environment_id,type}` before Turn creation. Connect the exact Session Environment through our scoped daemon enrollment. Three-harness Docker/E2B execution: E1; explicit initial pending-input/query/connection/native completion: E2; expiry: [controlled initial-input test](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/tests/official_self_hosted_initial.py). | Idle offline Sessions without pending input request nothing. Registration alone is not connectivity or native readiness. Stock `exec-server`/Noise transport is outside the approved V1 route. Exact upstream registration/action-removal timing remains unverified. | -| Stream disconnect and execution loss | SSE is live-only. Reconnect, buffer events, retrieve Session/Turn/Items and deduplicate Item IDs. Worker recovery fails previously claimed work without replay; queued work can remain. [Recovery contract](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/README.md#public-execution-admission), [connection reconciliation](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/store/environment_connection_recovery.go). | Client disconnect and daemon/Core loss are different cases. F3 qualifies client-stream loss and continued pending function handling; F2 qualifies native process loss with an unapplied saved result. Neither promises replay or recovery of unknown external effects. | - -## Required-action recovery contract - -The fixed [Session union](https://github.com/openai/openai-python/blob/d7c41efee1b0802b79f3f88a678ef2052b06e9ce/src/openai/types/beta/agent_session.py) -defines both variants. The official [Functions](https://developers.openai.com/api/docs/guides/agents-api/tools/functions) -and [Manage sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage) -guides, checked on 2026-09-22, direct clients to retrieve `required_actions` after -restart or stream loss. A historical `function_call` Item alone cannot establish -that a result is still pending. The fixed SDK governs field/type compatibility; -current prose does not silently change that pin. - -For a pending function, use the returned Session, Turn and call identity. If the -application already performed the function, keep and submit that saved result; -do not run an external effect again merely because an action remains visible. -Core's acknowledgement boundary is native application. For an environment action, -connect its exact Environment using the existing enrollment authorization. -[Connection observations](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/store/environment_connections.go) -fence stale generations; transport connection can clear pre-Turn activity before -native preparation. Neither registration nor an action disappearing proves that -a model ran successfully. Query the matching Turn and Items for its outcome. - -Two timing questions remain open. Repeated `requires_action` notification order -and acknowledgement timing are local implementation choices, not proven upstream -semantics. Also, an admitted result that is cancelled before native observation -can remain internally saved without a public output Item or `item.added`. -[Item publication](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/internal/store/item_projection.go) and -[the existing coverage record](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/README.md#public-function-configuration) preserve -this gap. Successful retry cannot manufacture the missing observation or establish -that the model consumed the result. - -## Evidence register - -Real records below use fixed SDK 3.13.0 and raw HTTP through Core, dedicated -PostgreSQL, daemon and native harness. Evidence is private under `~/.parsar/remediation/` on `zju_a100_2` and the -development host. Paths containing `validated/` or `server-evidence/` identify -downloaded local mirrors; summary files may also live only on the development -host. Locators identify retained evidence without publishing credentials or -private launch configuration. Revisions identify the accepted change, -not a claim that every historical workflow was rerun at the current baseline. - -| ID | Exact evidence and accepted scope | -| --- | --- | -| M1 | `20260922/message-image-input/public-codex-reviewed.log` (59.41s), `public-claude-reviewed.log` (79.52s), `public-mcode-network-fixed.log` (48.95s); [PR #12](https://github.com/MiniMax-AI/OpenAgentCore/pull/12), merge `37a2923`. Codex/Claude Kimi K3 PNG initial/active inputs, receipts, retries, cancellation, cold continuation and isolation; MiniMax M2.7 ordinary text regression. | -| M2 | `20260922/workspace-images/validation-summary.json`; Codex `public-run-_lr5uiy_`, Claude `public-run-sb65p9e9`; candidate `2c295116d66ed9aafc808ec49a8cb6dcb5c674c2`, merge `1adb2489bc3415039440224e9a7905c53e68a557` ([#17](https://github.com/MiniMax-AI/OpenAgentCore/pull/17)). Kimi K3, Codex 0.153.4, Claude SDK 0.3.269/native 2.1.269; Docker seven-Turn image/workspace workflow. Codex's receipt conclusion is superseded by F2. | -| F1 | `20260922/function-result-images/validation-summary.json`, `validated/function-image-public-2567456666/public.json`; candidate `d3cdb225bc7628b968b76c7e1b400101894ce8cd`, merge `fd23f169e1ede1b2f1c39a1d9dcce71886e3c006` ([#16](https://github.com/MiniMax-AI/OpenAgentCore/pull/16)). Claude SDK 0.3.269/native 2.1.269 with Kimi K3 on `none`; success PNG/JPEG, failed text, retries, cancellation, history continuation. Earlier Codex transport-only evidence does not qualify current receipts. | -| F2 | `20260922/function-result-receipts/validation-summary.json`, `candidate-public-owner-sdk.log`; hosted `public-run-4fn70foy` (104.13s), `none` `function-image-public-945075091` (83.918s). Candidate `6dceb98e1c56469fcc70cd82025ce77fc870ed3d`, merge `206474a4c10901442b1faa094281bfb5559082b5` ([#20](https://github.com/MiniMax-AI/OpenAgentCore/pull/20)); real Kimi, Codex 0.153.4. Qualifies native receipts, not completed provider consumption. | -| F3 | `20260922/execution-tools-closure/pending-actions/validation-summary.json`; Codex `codex/public-run-8gexf5a8` (65.58s), Claude `claude_sdk/public-run-5f2tr7e_` (74.33s), production source `206474a`. The same [public verifier](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/core/tests/official_pending_actions_native.py) checks disconnected-client pending queries, success/error/cancel, original results, target isolation, retry/conflict and no implicit call replay with real Kimi on Docker. No Core restart or native-loss injection is claimed by these runs. | -| S1 | `20260922/structured-output/acceptance-summary.json`, `structured-public-1905281777/public.json`; real candidate `7f533d46c472f3cdf7c16ce9471c225a2ba7eded`, merge `8716e699dbc34904499c94b6b0b03857bbebfaad` ([#11](https://github.com/MiniMax-AI/OpenAgentCore/pull/11)). Claude/Kimi `none` schema/function execution and cold continuation. Schema-specific active steering was not separately qualified here. | -| S2 | `20260922/hosted-structured-output/validation-summary.json`, `validated/public-inline.log`, `public-run-qvq3csf1` (186.09s); candidate `f6d2c3f2a1dc2ff5f177213bd2b20d78496011d0`, merge `aa85d8ecc60e0a8b7f2494b73caa81216ee197e2` ([#18](https://github.com/MiniMax-AI/OpenAgentCore/pull/18)). Claude SDK 0.3.269/native 2.1.269, real Kimi; Docker saved/inline schema, prepared/active input, native files and four completed structured answers. | -| D1 | `20260922/deferred-tools/tool-search-public-2039155387/public.json`, `public-image-isolated-tests.log` (86.71s); merge `178507ae7a63d4068e1e82bef9cd256ba398ae00` ([#13](https://github.com/MiniMax-AI/OpenAgentCore/pull/13)). Claude SDK 0.3.269/native 2.1.269/Kimi K3 `none`; text results with initial/active PNGs, cancellation and cold continuation. `claude-native-1790052750` separately records provider schema inventories and native feasibility. | -| P1 | `20260922/tool-policy/acceptance.json`, `server-evidence/tool-policy-{codex-2495445746,claude_sdk-2539346823,mcode-3747575401}/public.json`; candidate `eeb432c7495265ae3a9309e32f5b4323611c3245`, merge `4b8754a6eda6696d9b18eb8d583953ac16c6800f` ([#14](https://github.com/MiniMax-AI/OpenAgentCore/pull/14)). Codex/Claude Kimi K3, MiniMax M2.7; four `none` Sessions per harness, native disable controls and cold continuation. | -| E1 | `20260921/self-hosted-onboarding/{source-candidate.json,source-verified.json,live,live-e2b}`; candidate `8f0cd2530d7b58cb7fb3ea124a1fc43dacecca36`. [Exact Docker/E2B run paths and limits](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/user-managed-runtime-v1.md#evidence-and-verification-boundaries): Codex Kimi K3 Responses, Claude Kimi K3 Anthropic-compatible API, MiniMax M2.7, immutable Linux amd64 Runtime builds. Native execution, restart/history, cancellation, Files/Artifacts and isolation; shared credential lifecycle evidence is not a separate live rotation run for every E2B profile. | -| E2 | `20260922/execution-tools-closure/environment-actions/result.json` contains Codex/Claude Kimi passes (13 checks each) and the retained MiniMax direct-network failure; `mcode-relay-retry/result.json` separately passes MiniMax M2.7 (13 checks) after correcting provider routing. Source `206474a`; same shared SDK/raw workflow, isolated Core/PostgreSQL and user-managed Docker. Covers initial creation SSE, client disconnect, exact pending Environment/no Turn or Items, scoped enrollment, one actual completed model Turn and creation retries preserving history. This is connection-action qualification, not another full lifecycle or E2B regression. | - -Controlled tests establish parser, projection, atomicity and race behavior; native -feasibility probes establish only feasibility. Neither replaces the real records. -Failed setup, provider and assertion runs remain failures with their original -scope. The unchanged gate requirements and independent review apply to this batch. - -## Milestone closure and remaining limits - -1. **Principal function recovery:** F3 directly verifies live client-stream loss - while a function is pending on Codex and Claude, authoritative queries, exact - targeting, rejection without mutation, original results, retry/conflict, - application, cancellation and isolation. F2 separately establishes truthful - native-loss settlement without replay. No active execution recovery is promised. -2. **Principal environment recovery:** E2 explicitly verifies pending - `environment_connection` recovery and single initial execution on all three - harnesses. E1 retains broader deployment/history/isolation qualification. - Registration, connection and preparation remain distinct; no exact upstream - timing or arbitrary-provider qualification is inferred. -3. **Recorded nonblocking timing:** an accepted result cancelled before native - application may lack a public result Item. The submitted data remains durable; - F2 confirms that native loss does not turn unknown delivery into Applied. The - fixed sources do not establish the publication point for this interleaving. - Keep it queued rather than inventing a public state or rewriting safe receipt - ownership. This limited timing question is not accepted protocol parity and - does not invalidate F3's principal pending-result workflow. - -Approved native capability differences (including default PTC), unsupported optional -combinations, arbitrary provider parity and low-frequency error/default edge cases -remain separate limitations. They do not authorize silently relabeling an unproved -principal workflow as deferred. OAuth, full Usage, release publication, new tool -kinds and new execution loops are outside this closure batch. - -[Repository source](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/execution-tools.md) diff --git a/apps/docs/content/docs/api-reference/agents.mdx b/apps/docs/content/docs/api-reference/agents.mdx deleted file mode 100644 index 25bd137d4..000000000 --- a/apps/docs/content/docs/api-reference/agents.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Agents -description: >- - Agents. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists only the authenticated tenant's saved Agents, independently of - Sessions. Limit 0 is treated as 1 and larger limits as 100, as - observed on the hosted service. The local default is 20; exact - upstream default/cap and empty cursor fields remain unverified. An - unknown, malformed or foreign after cursor returns not found. - - content: >- - Persists configuration independently of execution. Names over 128 - characters and metadata outside 16 string pairs with 64-character keys - and 512-character values return invalid_request_error with the - official param; U+0000 in stored strings is rejected as a local - storage limit. As on every Agents API JSON route, a non-JSON - Content-Type, invalid UTF-8, malformed JSON, a repeated key at any - depth or a non-object root returns invalid_request_error with a null - param and the official message before other checks; an empty or null - body is {}. Missing, unknown, wrongly typed or unsupported enum - members of the pinned configuration shapes (tools, text, reasoning, - service_tier, multi_agent) return invalid_request_error with the JSON - path as param; duplicate function names, repeated web_search or - tool_search and non-object schema root types return it with a null - param. Supports model/name/instructions/metadata, explicit reasoning - and service tiers, multi_agent, text/json_schema, - function/tool_search/programmatic_tool_calling/web_search and HTTP MCP - with nullable credential_id, service origin (omitted or null on HTTP - transport is saved as service) and boolean required defaulting to - false. Saving credential_id grants no access: Session admission checks - attached Vault ownership and destination. MCP allowed_tools preserves - null versus empty; saved HTTP transport includes empty headers. - Model-derived reasoning defaults, other MCP variants and public retry - conformance remain incomplete. web_search saves every pinned mode: - omitted or null mode is saved as live and omitted or null context_size - as medium; allowed_domains preserves null versus empty and a present - location, including {}, includes all four keys with null for omitted - ones, as observed officially (req_db41d2f6261b4abfb69465eafe719ab5, - req_165d53b88445490b9146d8272c54134d). Session execution accepts only - explicit disabled web_search and disabled programmatic_tool_calling - through qualified Runtime controls; saved enabled forms reject at - Session admission. Session execution admits only its supported - configuration subset. - - content: >- - Reads the saved resource owned by the authenticated tenant, - independently of execution Sessions. - - content: >- - Preserves omitted fields and replaces supplied fields using shared - saved-configuration validation. Null name/instructions clear; null or - empty metadata clears all pairs. Name, metadata and configuration - validation errors return invalid_request_error with the official - param, using the Agent create rules before the Agent lookup. Existing - Session snapshots are unchanged. Empty updates advance updated_at - without changing saved fields. Nested replacement/null defaults, - model-derived reasoning and exact hosted error behavior remain - incompletely verified. - - content: >- - Deletes only the authenticated tenant's saved configuration. Existing - Session snapshots, history and recorded creation retry identities - remain independent. Missing and repeated deletion locally return404; - exact hosted error and in-flight creation/deletion semantics remain - unverified. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/artifacts.mdx b/apps/docs/content/docs/api-reference/artifacts.mdx deleted file mode 100644 index 012154e5f..000000000 --- a/apps/docs/content/docs/api-reference/artifacts.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Artifacts -description: >- - Artifacts. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists published outputs independently of Environment availability. - Sorting uses publication time and ID. A later Turn publishes a path - again only when it is new, its bytes changed, or no Artifact remains - for it. A malformed environment_id matches nothing. An after value - that is not an Artifact of this Session, including a malformed one, - returns 400 invalid_request_error with the message "after is not a - valid artifact ID". The local default page size is 20; exact upstream - defaults remain unverified. - - content: >- - Deletes the published copy without modifying its original workspace - file. Already admitted content reads may finish; later reads reject. - - content: >- - Streams stored bytes after tenant and Session authorization, including - after Environment expiration. Exact upstream headers and Range - behavior remain unverified. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/administrator-projects.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects.mdx deleted file mode 100644 index 81b0dd3ca..000000000 --- a/apps/docs/content/docs/api-reference/core/administrator-projects.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Administrator Projects -description: >- - Administrator Projects. Core administration API: Core key held by Web’s server - or an operator script. Generated local management contract. This is not part - of the public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: [] ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/agents.mdx b/apps/docs/content/docs/api-reference/core/agents.mdx deleted file mode 100644 index 3efbe8afb..000000000 --- a/apps/docs/content/docs/api-reference/core/agents.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Agents -description: >- - Agents. Core administration API: Core key held by Web’s server or an operator - script. Generated local management contract. This is not part of the public - OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/artifacts.mdx b/apps/docs/content/docs/api-reference/core/artifacts.mdx deleted file mode 100644 index 94f4020b7..000000000 --- a/apps/docs/content/docs/api-reference/core/artifacts.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Artifacts -description: >- - Artifacts. Core administration API: Core key held by Web’s server or an - operator script. Generated local management contract. This is not part of the - public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration.mdx b/apps/docs/content/docs/api-reference/core/core-administration.mdx deleted file mode 100644 index 0ed580f68..000000000 --- a/apps/docs/content/docs/api-reference/core/core-administration.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Core Administration -description: >- - Core Administration. Core administration API: Core key held by Web’s server or - an operator script. Generated local management contract. This is not part of - the public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Newest-first cursor pagination of safe metadata. Actor - labels are unverified console labels, not authorization identities. - Request bodies and secrets are never recorded. - - content: >- - Core key only; available before any sandbox deployment exists. Reports - the public URL that applications, nodes, sandboxes and self-hosted - executors use, the API base URL, Core's source commit and installation - ID, the installer's settings snapshot with where to change it, and - what is bound to the current public URL. Sensitive settings report - only whether they are configured. - - content: >- - Core key only. Complete UTC buckets; unknown measurements are null. - Samples are process-local and are not backfilled after a restart. - - content: >- - Core key only. Reports actual resource disposition, including expiry - and failure cleanup. This is not archive provenance and does not - assert active Turn settlement. Read this after an uncertain archive - response; never infer released from a missing sandbox alone. - - content: >- - Core key only. Requires the current deployment generation; no - maintenance mode is required. Permanently closes execution, requests - cancellation and releases sandbox/snapshots through existing cleanup. - Session history and persisted files/artifacts remain; unpersisted - workspace contents are lost. A cleanup_pending response is not proof - of resource release. Does not affect caller-managed Runtime. - - content: >- - Core key only. Each observation is labelled with its owning Project - ID. Uses the existing read-only Runtime sampler, with bounded - concurrency and no execution or provisioning. A provider with a batch - metrics read, such as E2B, samples the page's running sandboxes in one - bounded request. - - content: >- - Core key only. after/limit/order paginate Projects. Agent grouping - returns groups within those spaces. Date bounds filter Session - creation, not current asset counts. Usage sums only non-null public - Session usage; coverage includes every selected Session. Each Project - is read in a consistent database snapshot. Totals are not billing - records. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/credentials.mdx b/apps/docs/content/docs/api-reference/core/credentials.mdx deleted file mode 100644 index f28389c4e..000000000 --- a/apps/docs/content/docs/api-reference/core/credentials.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Credentials -description: >- - Credentials. Core administration API: Core key held by Web’s server or an - operator script. Generated local management contract. This is not part of the - public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/deployment-model-providers.mdx b/apps/docs/content/docs/api-reference/core/deployment-model-providers.mdx deleted file mode 100644 index 0ead2b602..000000000 --- a/apps/docs/content/docs/api-reference/core/deployment-model-providers.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Deployment Model Providers -description: >- - Deployment Model Providers. Core administration API: Core key held by Web’s - server or an operator script. Generated local management contract. This is not - part of the public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Returns every harness this build supports, in name - order. enabled and default are read-only views of the process - configuration (OAC_DEFAULT_HARNESS and OAC_HARNESSES). - model_configuration is the harness's deployment default, stored in - Core, or null. Keys are never returned; api_key_configured reports - that one is set. - - content: >- - Core key only. Returns the safe view; the key is never returned. 404 - when the harness does not exist or has no deployment default. Nullable - last_used_at, last_error_code and last_error_at are best-effort - observations of committed root Turns using this exact default - revision; they do not establish current readiness and may remain stale - indefinitely. - - content: >- - Core key only. Idempotent; each successful request is audited. - Sessions that already froze the default keep it. Afterwards new - openai_hosted Sessions for this harness need a Session or Agent - bundle. - - content: >- - Core key only. Replaces one complete deployment model configuration, - including its write-only provider key. Validates through the selected - Harness declaration and freezes the resolved configuration for new - Sessions; existing Sessions are unchanged. See - contracts/agents-api/model-execution.md#deployment-defaults for - fields, source precedence and observation rules. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/environment-templates.mdx b/apps/docs/content/docs/api-reference/core/environment-templates.mdx deleted file mode 100644 index 1f2754d5f..000000000 --- a/apps/docs/content/docs/api-reference/core/environment-templates.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Environment Templates -description: >- - Environment Templates. Core administration API: Core key held by Web’s server - or an operator script. Generated local management contract. This is not part - of the public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/execution-configuration.mdx b/apps/docs/content/docs/api-reference/core/execution-configuration.mdx deleted file mode 100644 index 207d504b0..000000000 --- a/apps/docs/content/docs/api-reference/core/execution-configuration.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Execution configuration -description: >- - Execution configuration. Core administration API: Core key held by Web’s - server or an operator script. Generated local management contract. This is not - part of the public OpenAI API. -full: true -_openapi: - method: GET - route: /core/v1/projects/{project_id}/sessions/{session_id}/execution-configuration - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only; the Project ID selects the target space and does not - authenticate. Returns the committed model, harness and safe provider - selection with recorded sources. This read never decrypts credentials, - resolves current defaults or probes execution health. Deployment - defaults frozen after they moved into Core show their safe view; older - deployment selections remain redacted. Historical provenance and - missing provider projections are explicitly unknown/unavailable. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/executor-credentials.mdx b/apps/docs/content/docs/api-reference/core/executor-credentials.mdx deleted file mode 100644 index 2ef8db657..000000000 --- a/apps/docs/content/docs/api-reference/core/executor-credentials.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Executor Credentials -description: >- - Executor Credentials. Core administration API: Core key held by Web’s server - or an operator script. Generated local management contract. This is not part - of the public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Returns metadata of the credentials restricted to this - Environment, oldest first; secrets are never listed. Connection - combines current credential authority and an open matching gateway - peer; timestamps are historical observations, not readiness. Without a - gateway it is never connected. The Environment must be a self_hosted - Environment of the Project whose Session exists; otherwise 404. - - content: >- - Core key only. Returns a connect-only secret once, restricted to - daemon enrollment and connection for this Environment, with the - Project's principal as its execution principal. Repeating an issuance - key_id returns 409 executor_credential_exists; after an uncertain - response, list the credentials and rotate that key_id explicitly. - Rotation keeps the key's Environment, invalidates the old secret and - restores a revoked key; rotating an unknown key_id returns 404. In an - archived Project, issuance and rotation return 409 project_archived. - The Environment must be a self_hosted Environment of the Project whose - Session exists; otherwise 404. Each write records an administrator - audit entry without the secret. - - content: >- - Core key only. Revokes one credential restricted to this Environment; - repeated revocation is safe and it also works in an archived Project. - Revocation denies future enrollment and connection but does not stop - executor-owned compute. The Environment must be a self_hosted - Environment of the Project whose Session exists; otherwise 404. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/files.mdx b/apps/docs/content/docs/api-reference/core/files.mdx deleted file mode 100644 index 186f103bb..000000000 --- a/apps/docs/content/docs/api-reference/core/files.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Files -description: >- - Files. Core administration API: Core key held by Web’s server or an operator - script. Generated local management contract. This is not part of the public - OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/index.mdx b/apps/docs/content/docs/api-reference/core/index.mdx deleted file mode 100644 index ad2fc6c57..000000000 --- a/apps/docs/content/docs/api-reference/core/index.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Core administration API -description: /core/v1 — Core key held by Web’s server or an operator script. ---- - -Generated local management contract. This is not part of the public OpenAI API. - -**Credential:** Core key held by Web’s server or an operator script. Examples use reserved `example.com` origins. This reference does not send requests or collect credentials. - -Operator scripts use Core’s loopback port. The public entry routes management through Web, which requires its signed-in session and supplies the Core key on the server. - -[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) - -- [core-administration](/api-reference/core/core-administration) -- [deployment-model-providers](/api-reference/core/deployment-model-providers) -- [administrator-projects](/api-reference/core/administrator-projects) -- [agents](/api-reference/core/agents) -- [environment-templates](/api-reference/core/environment-templates) -- [executor-credentials](/api-reference/core/executor-credentials) -- [native-installation](/api-reference/core/native-installation) -- [files](/api-reference/core/files) -- [write-audit](/api-reference/core/write-audit) -- [sessions](/api-reference/core/sessions) -- [artifacts](/api-reference/core/artifacts) -- [execution-configuration](/api-reference/core/execution-configuration) -- [items](/api-reference/core/items) -- [runtime-history](/api-reference/core/runtime-history) -- [runtime-observations](/api-reference/core/runtime-observations) -- [turns](/api-reference/core/turns) -- [skills](/api-reference/core/skills) -- [vaults](/api-reference/core/vaults) -- [credentials](/api-reference/core/credentials) -- [sandbox-manager](/api-reference/core/sandbox-manager) diff --git a/apps/docs/content/docs/api-reference/core/items.mdx b/apps/docs/content/docs/api-reference/core/items.mdx deleted file mode 100644 index 7589bc49b..000000000 --- a/apps/docs/content/docs/api-reference/core/items.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Items -description: >- - Items. Core administration API: Core key held by Web’s server or an operator - script. Generated local management contract. This is not part of the public - OpenAI API. -full: true -_openapi: - method: GET - route: /core/v1/projects/{project_id}/sessions/{session_id}/items - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/meta.json b/apps/docs/content/docs/api-reference/core/meta.json deleted file mode 100644 index fb07e650d..000000000 --- a/apps/docs/content/docs/api-reference/core/meta.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "title": "Core administration API", - "pages": [ - "index", - "core-administration", - "deployment-model-providers", - "administrator-projects", - "agents", - "environment-templates", - "executor-credentials", - "native-installation", - "files", - "write-audit", - "sessions", - "artifacts", - "execution-configuration", - "items", - "runtime-history", - "runtime-observations", - "turns", - "skills", - "vaults", - "credentials", - "sandbox-manager" - ] -} diff --git a/apps/docs/content/docs/api-reference/core/native-installation.mdx b/apps/docs/content/docs/api-reference/core/native-installation.mdx deleted file mode 100644 index a03fdfca8..000000000 --- a/apps/docs/content/docs/api-reference/core/native-installation.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Native Installation -description: >- - Native Installation. Core administration API: Core key held by Web’s server or - an operator script. Generated local management contract. This is not part of - the public OpenAI API. -full: true -_openapi: - method: GET - route: /core/v1/projects/{project_id}/environments/{environment_id}/installation - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. The commands contain a 30-minute installation - authorization, never an executor secret. Web displays these same - commands provided in public Session creation and detail responses. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/runtime-history.mdx b/apps/docs/content/docs/api-reference/core/runtime-history.mdx deleted file mode 100644 index 5b7e2da6f..000000000 --- a/apps/docs/content/docs/api-reference/core/runtime-history.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Runtime history -description: >- - Runtime history. Core administration API: Core key held by Web’s server or an - operator script. Generated local management contract. This is not part of the - public OpenAI API. -full: true -_openapi: - method: GET - route: /core/v1/projects/{project_id}/sessions/{session_id}/runtime-history - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only; the Project ID selects the target space and does not - authenticate. Returns stored Runtime observations for one Session. End - is exclusive; the server selects a bounded resolution. Responses - contain at most 1,000 series, 10,000 points per coverage/series array, - and 100,000 total coverage plus series points. It never reads or - changes live compute. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/runtime-observations.mdx b/apps/docs/content/docs/api-reference/core/runtime-observations.mdx deleted file mode 100644 index b9a2917ae..000000000 --- a/apps/docs/content/docs/api-reference/core/runtime-observations.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Runtime observations -description: >- - Runtime observations. Core administration API: Core key held by Web’s server - or an operator script. Generated local management contract. This is not part - of the public OpenAI API. -full: true -_openapi: - method: GET - route: /core/v1/projects/{project_id}/sessions/{session_id}/runtime-observation - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only; the Project ID selects the target space and does not - authenticate. Returns one read-only current Runtime observation. It - never provisions, renews, restarts, pauses or stops compute. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager.mdx deleted file mode 100644 index de80e6d5a..000000000 --- a/apps/docs/content/docs/api-reference/core/sandbox-manager.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Sandbox Manager -description: >- - Sandbox Manager. Core administration API: Core key held by Web’s server or an - operator script. Generated local management contract. This is not part of the - public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Does not grant project resource access. Responses - contain only explicit safe fields. E2B template_build values are those - Core read when the selection was saved; this read does not call E2B. - - content: >- - Selects a provider, enforced resource limits and pinned Runtime - release. Core derives the deployment's core_url from the installation - public URL and rejects a core_url member with 400. E2B returns 409 - sandbox_configuration_error while the public URL is loopback. E2B - credentials are write-only. E2B may omit resources to adopt the - validated template build's CPU and memory, returned in - specification.resources. Requires explicit expected_generation, - including zero at first setup. Stale retries reject before provider - validation. An identical selection at the current generation is a - no-op; differing selections and file-managed deployments reject. This - does not create compute or execute work. - - content: >- - Requires the observed generation, the same backend type and no active - reset. E2B same-team changes apply online: allocations retain - immutable generation and current credentials; omitted api_key - preserves it, explicit submission including the same key verifies and - advances generation. Other teams require explicit reset. Node - providers retain the zero-resource guard and retire old nodes/tokens - on change. Core rejects core_url input. Never automatically replay an - uncertain write; rollout.state is the authoritative preparation - polling signal. - - content: >- - Archives hosted Sessions and waits for confirmed provider cleanup, - preserving history and Files/Artifacts. Auto waits for started or - waiting Turns and file writes until the durable deadline; force - cancels them. The same clear is idempotent; force escalates auto. - Requires the current generation. Self-hosted Sessions are unchanged. - - content: >- - Restores admission but never restores Sessions already archived. With - no reset running this is an idempotent read, provided the generation - still matches. - - content: >- - Core key only. Uses a transient E2B credential and endpoint through - the pinned SDK helper; returns safe template metadata. Does not save - the credential or allocate compute. - - content: >- - Core key only. Reads one template through the pinned SDK helper with a - transient E2B credential. Returns ready builds only, without - allocating compute. - - content: >- - Core key only. Does not grant project resource access. Responses - contain only explicit safe fields. - - content: >- - Core key only. Does not grant project resource access. Responses - contain only explicit safe fields. - - content: >- - Core key only. Complete UTC buckets. Missing host measurements and - offline history are null; reads never sample or backfill. - - content: >- - Core key only. Does not grant project resource access. Responses - contain only explicit safe fields. - - content: >- - Core key only. Does not grant project resource access. Responses - contain only explicit safe fields. - - content: >- - Core key only. Does not grant project resource access. Responses - contain only explicit safe fields. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sessions.mdx b/apps/docs/content/docs/api-reference/core/sessions.mdx deleted file mode 100644 index a266de5f0..000000000 --- a/apps/docs/content/docs/api-reference/core/sessions.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Sessions -description: >- - Sessions. Core administration API: Core key held by Web’s server or an - operator script. Generated local management contract. This is not part of the - public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Safe failure categories from one committed snapshot; no - native text or historical inference. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills.mdx b/apps/docs/content/docs/api-reference/core/skills.mdx deleted file mode 100644 index 1521c7fb9..000000000 --- a/apps/docs/content/docs/api-reference/core/skills.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Skills -description: >- - Skills. Core administration API: Core key held by Web’s server or an operator - script. Generated local management contract. This is not part of the public - OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/turns.mdx b/apps/docs/content/docs/api-reference/core/turns.mdx deleted file mode 100644 index d21b08bb2..000000000 --- a/apps/docs/content/docs/api-reference/core/turns.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Turns -description: >- - Turns. Core administration API: Core key held by Web’s server or an operator - script. Generated local management contract. This is not part of the public - OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. At most 1000 root Item receipt timings in public Item - order. Receipt intervals are not native execution durations. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/vaults.mdx b/apps/docs/content/docs/api-reference/core/vaults.mdx deleted file mode 100644 index 552e8e9de..000000000 --- a/apps/docs/content/docs/api-reference/core/vaults.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Vaults -description: >- - Vaults. Core administration API: Core key held by Web’s server or an operator - script. Generated local management contract. This is not part of the public - OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. - - content: >- - Core key only. Reuses the public resource projection and operation - rules; the Project ID selects the target space and does not - authenticate. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/write-audit.mdx b/apps/docs/content/docs/api-reference/core/write-audit.mdx deleted file mode 100644 index 70eed9da8..000000000 --- a/apps/docs/content/docs/api-reference/core/write-audit.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Write Audit -description: >- - Write Audit. Core administration API: Core key held by Web’s server or an - operator script. Generated local management contract. This is not part of the - public OpenAI API. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Core key only. The Project ID path selects its space. Returns null for - resources without recorded creation provenance, including historical - and foreign resources. No key secret is returned. - - content: >- - Core key only. Reverse chronological keyset pagination over committed - writes. Creation records remain; other records follow configured - retention. The key path selects its independent space, never a - caller-supplied tenant. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/credentials.mdx b/apps/docs/content/docs/api-reference/credentials.mdx deleted file mode 100644 index b75f46360..000000000 --- a/apps/docs/content/docs/api-reference/credentials.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Credentials -description: >- - Credentials. Application API: Project API key. Public schema constrained by - the pinned OpenAI Agents API baseline; documented x_agents_core fields remain - Core extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists only metadata from the authenticated project's requested Vault, - without decryption or execution. An unknown, malformed or foreign - after cursor, including another Vault's Credential, returns not found. - Includes active and archived Credentials by default, independently of - Vault status. Status accepts a scalar, the SDK status[] array or both, - filtering by their union; a repeated scalar is rejected. Limits - default to 20 and clamp to 1–100. Equal creation times use ID - ordering. Hosted errors, concurrent-page behavior and archive/delete - lifecycle remain unverified or unimplemented. - - content: >- - Stores static_bearer or mcp_oauth secrets as execution-owned - authenticated ciphertext without contacting any endpoint. Static - bearer and OAuth access tokens must be nonempty strings; their bytes - are preserved. OAuth accepts a required access token, nullable RFC3339 - expiry and optional refresh configuration with none, - client_secret_basic or client_secret_post authentication. Required - name is trimmed to 1–256 UTF-8 bytes. Credential and token endpoints - require HTTPS without userinfo or fragments. Responses contain safe - metadata only, including explicit nullable OAuth expiry, refresh, - resource and scope. Missing encryption configuration returns local - 503. External authorization and provider revocation remain caller - responsibilities; exact hosted error/default semantics remain - unverified. - - content: >- - Reads only non-secret metadata scoped to the authenticated project and - owning Vault. No token decryption, network request or execution is - performed. Unknown, foreign, wrong-Vault and malformed IDs use the - same local not-found response; hosted error parity remains unverified. - - content: >- - Explicitly empty static bearer or OAuth access tokens and OAuth - patches without a mutable field are rejected before storage. Omitted - OAuth access tokens preserve the existing grant when expiry or refresh - fields change. Updates the existing static_bearer or mcp_oauth - authentication method without network requests. OAuth access_token - omission/null retains the token; a new token clears omitted expiry, - explicit null clears expiry, and other omitted fields remain - unchanged. OAuth refresh patches cannot add configuration or change - client, endpoint, resource or authentication method; nullable - token/client-secret values retain stored secrets while explicit null - scope clears scope. Whole-null refresh and token_endpoint_auth retain - existing configuration under local policy. Identity, destination, - creation time and Session bindings remain unchanged. Responses expose - safe metadata only. Already-dispatched work is not revoked; provider - revocation, storage-key rotation and exact hosted - concurrent-update/error semantics remain separate. - - content: >- - Removes one Credential and its encrypted token within the - authenticated project and owning Vault, without an encryption key or - secret decryption. Subsequent metadata reads, updates and dispatch - lookups cannot use it. Existing Session snapshots and history retain - their frozen identities; already-resolved tokens and running Sessions - are not revoked or cancelled. This local policy removes the row rather - than defining archived lifecycle; missing/repeated deletion returns - 404. Exact hosted archive, post-delete visibility and retry/error - semantics remain unverified. Provider revocation and physical erasure - from native history, WAL or backups are separate concerns. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environment-templates.mdx b/apps/docs/content/docs/api-reference/environment-templates.mdx deleted file mode 100644 index 32e05af1a..000000000 --- a/apps/docs/content/docs/api-reference/environment-templates.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Environment Templates -description: >- - Environment Templates. Application API: Project API key. Public schema - constrained by the pinned OpenAI Agents API baseline; documented x_agents_core - fields remain Core extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists tenant-owned safe template metadata in creation order with ID - tie-breaking. Defaults to limit 20 and descending order; limit 0 is - treated as 1 and larger limits as 100. Foreign, missing and malformed - cursors return the same not found error. Concurrent-page and exact - hosted error behavior remain unverified. - - content: >- - Saves tenant-owned hosted configuration. Supports nullable name, - enabled/disabled or exact-domain restricted network, initial - inline/file_id files, confidential env, ordered setup_commands, - npm/Python packages inline/referenced Skill ZIPs, Plugin ZIPs and - workspace-contained capability directories. Omitted/null network - defaults to enabled. Restricted network requires 1–100 exact ASCII - hostnames; other host forms and populated unsupported installations - are rejected before persistence without echoing input. Network policy - rejections return invalid_request_error with a null param. System - dependencies must be preinstalled in the sandbox image or template, or - on the host machine; packages.system is rejected. No compute is - allocated. Exact hosted error/retry semantics remain unverified. - - content: >- - Returns safe tenant-owned configuration metadata without allocating - compute. Missing and foreign resources return the same not-found - response. - - content: >- - Supplied fields replace atomically; omitted fields remain unchanged. - Null name clears and null network resets to the pinned enabled - default. Existing Session snapshots and creation retries remain - unchanged. Initial files replace as a list; null/empty clears. File - data is encrypted separately and excluded from response metadata. - Skills replace as a list; null/empty clears. Skill archives are - encrypted separately and omitted from responses. Plugins and - capability directories replace as lists; null/empty clears. Plugin - archives are encrypted and omitted from responses. Capability - directories are snapshotted after setup. Environment MCP execution - requires a qualified native transport and runtime network policy. - Empty updates advance updated_at without changing saved fields or - confidential contents. Network policy rejections return - invalid_request_error with a null param. - - content: >- - Deletes the tenant-owned reusable configuration without changing or - deleting existing Sessions and their frozen configuration. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environments.mdx b/apps/docs/content/docs/api-reference/environments.mdx deleted file mode 100644 index 287d4db3f..000000000 --- a/apps/docs/content/docs/api-reference/environments.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Environments -description: >- - Environments. Application API: Project API key. Public schema constrained by - the pinned OpenAI Agents API baseline; documented x_agents_core fields remain - Core extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Returns durable connection status and safe installed metadata for - supported self_hosted and basic openai_hosted profiles. Initial files - expose frozen safe metadata without content; Plugin/Skill entries - expose only safe configured installation metadata. - Capability-directory discoveries are not added to those arrays. - Unsupported installation configurations remain implementation gaps. - This read does not prepare execution, start compute or require an - enabled execution worker. Session deletion removes the associated - Environment from public reads; project-shared read authorization is - unchanged. Connection status does not prove native readiness or - process quiescence. - - content: >- - Lists direct regular files in one authorized self_hosted or qualified - local workspace directory. Local paths use the public /workspace root - and must be in cleaned form. This partial implementation defaults to - the workspace root and limit 20; recursive scope and these defaults - are not verified upstream semantics. A missing path, a regular file or - a symbolic link returns an empty page; links are never followed. - Daemons without a local workspace binding use the Claude SDK adapter - reader, which keeps 404 for a missing path and 503 for a regular file - or symbolic link. Well-formed unknown query keys are ignored; - malformed query encoding and a repeated supported key are rejected. - Sorts by case-sensitive path components, descending by default. Keep - the same path, order and limit when using page. Each page rereads the - complete bounded directory; changed file paths/sizes invalidate - continuation locally with 400. There is no snapshot guarantee. An - openai_hosted Environment that has not connected yet returns 400. - Truncated or uncertain native results fail with 503 without returning - a partial page. This read never starts a Turn or admits model input. - Actual transport disconnect/reconnect events remain observable. - - content: >- - Uploads standard Base64 bytes to a file beneath /workspace in a - qualified local Environment and returns 201. Accepts inline bytes or a - project-owned source file_id through the same write path. Unknown body - fields are rejected with their name as param. Basic public hosted - creation requires explicit managed Runtime configuration; an - openai_hosted Environment that has not connected yet returns 400. - Inline data is limited to 5 MiB decoded and a file_id copy to 50 MiB. - Missing parent directories are created with mode 0700 and the file - with mode 0600. An existing destination is never replaced; a - directory, an existing file or a path through a symlink or - non-directory returns 400. Idle writes exclude execution. Missing - receipts return unavailable and retain a durable mutation gate without - automatic replay. Error/timing parity with upstream remains - unverified. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/events.mdx b/apps/docs/content/docs/api-reference/events.mdx deleted file mode 100644 index f0b0639a7..000000000 --- a/apps/docs/content/docs/api-reference/events.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Events -description: >- - Events. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - method: GET - route: /agents/sessions/{session_id}/events - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Live-only events, including command output fragments from capable - Codex peers as agent.output.command_execution_output.delta with stable - Item/output indexes. Native text conversion and output quotas apply; - completion snapshots remain authoritative. Reconnect through Session, - Turn and Items reads; missed events are not replayed. A lagging stream - closes with an error when its bounded buffer is exceeded. When a - hosted Environment fails to provision, the stream sends - agent.session.environment.failed, an error event - (environment_error/sandbox_error with the safe step and exit-status - reason, never command output) and agent.session.failed, then ends. - Session activity includes immutable pending-input connection actions - before Turn creation; self_hosted environments use the same safe - output as Session retrieval. - - Active streams revalidate the original Project key every second before - output; revocation, Project archival or authentication unavailability - closes the stream. Authentication checks use a five-second timeout. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/files.mdx b/apps/docs/content/docs/api-reference/files.mdx deleted file mode 100644 index 21b1c0709..000000000 --- a/apps/docs/content/docs/api-reference/files.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Files -description: >- - Files. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists project-owned Files without reading their bodies. The limit - defaults to 10000 and must be 1–10000. Equal creation times use ID - ordering. Purpose validation precedes cursor lookup; current storage - contains only user_data. An explicit empty purpose is treated as - omitted. Repeated purpose values remain rejected. Hosted positive - filtering, default order and concurrent-page behavior remain - unverified. No Beta header is required. - - content: >- - Accepts one multipart file and purpose=user_data in either order, with - a private 512 MiB content limit and 64 KiB envelope allowance. Commits - only after the entire request validates. The source is project-owned, - independent of Sessions and workspace copies. No Beta header is - required. Other purposes, expires_after, listing, resumable Uploads, - quotas/rate-limit and complete hosted error/status parity remain - unsupported or unverified. - - content: >- - Returns immutable project-owned user_data file metadata. No Beta - header is required. Other purposes, expiration and full hosted - status/error semantics remain unimplemented or unverified. - - content: >- - Atomically deletes project-owned metadata and stored bytes. - Already-admitted reads or copies may finish. Workspace copies remain - independent. Historical WAL/backups are not erased. No Beta header is - required; exact hosted concurrent deletion/error semantics remain - unverified. - - content: >- - Resolves project-owned File metadata before enforcing download policy. - Public download of user_data Files returns 400; missing and foreign - Files return the same 404. Internal initial-file and workspace copies - remain available. No Beta header is required. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/index.mdx b/apps/docs/content/docs/api-reference/index.mdx deleted file mode 100644 index e2bee0bf0..000000000 --- a/apps/docs/content/docs/api-reference/index.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Application API -description: /v1 — Project API key. ---- - -Public schema constrained by the pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core extensions. - -**Credential:** Project API key. Examples use reserved `example.com` origins. This reference does not send requests or collect credentials. - -[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) - -- [agents](/api-reference/agents) -- [environments](/api-reference/environments) -- [environment-templates](/api-reference/environment-templates) -- [sessions](/api-reference/sessions) -- [artifacts](/api-reference/artifacts) -- [events](/api-reference/events) -- [items](/api-reference/items) -- [subagents](/api-reference/subagents) -- [turns](/api-reference/turns) -- [files](/api-reference/files) -- [skills](/api-reference/skills) -- [vaults](/api-reference/vaults) -- [credentials](/api-reference/credentials) diff --git a/apps/docs/content/docs/api-reference/items.mdx b/apps/docs/content/docs/api-reference/items.mdx deleted file mode 100644 index 1c010f4b0..000000000 --- a/apps/docs/content/docs/api-reference/items.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Items -description: >- - Items. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - method: GET - route: /agents/sessions/{session_id}/items - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Returns supported message and tool Items in first-observation order. - Native engine fields are projected explicitly; unfinished Items on - terminal Turns are incomplete. Cursors are Items of the same tenant - and Session. Any other after value, including a malformed one, returns - 400 invalid_request_error with the message "Invalid session item ID in - `after`". ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/machine/index.mdx b/apps/docs/content/docs/api-reference/machine/index.mdx deleted file mode 100644 index a6d699b4d..000000000 --- a/apps/docs/content/docs/api-reference/machine/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Machine connection API -description: /api/v1 — Route-specific node enrollment, node, daemon, or executor credential. ---- - -Generated local machine contract. These connections reach Core directly, never through Web. - -**Credential:** Route-specific node enrollment, node, daemon, or executor credential. Examples use reserved `example.com` origins. This reference does not send requests or collect credentials. - -This schema covers node configuration, enrollment and identity. Daemon WebSockets and executor connection details are described in the [machine overview](/public-api#machine-connection-api). - -[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) - -- [native-installation](/api-reference/machine/native-installation) -- [sandbox-node](/api-reference/machine/sandbox-node) diff --git a/apps/docs/content/docs/api-reference/machine/meta.json b/apps/docs/content/docs/api-reference/machine/meta.json deleted file mode 100644 index 5d07906a3..000000000 --- a/apps/docs/content/docs/api-reference/machine/meta.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "title": "Machine connection API", - "pages": [ - "index", - "native-installation", - "sandbox-node" - ] -} diff --git a/apps/docs/content/docs/api-reference/machine/native-installation.mdx b/apps/docs/content/docs/api-reference/machine/native-installation.mdx deleted file mode 100644 index 80f373a71..000000000 --- a/apps/docs/content/docs/api-reference/machine/native-installation.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Native Installation -description: >- - Native Installation. Machine connection API: Route-specific node enrollment, - node, daemon, or executor credential. Generated local machine contract. These - connections reach Core directly, never through Web. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Accepts a short-lived Environment installation Bearer authorization, - not a Project or Core key. Returns frozen connection constraints; it - does not claim or rotate credentials. - - content: >- - A valid installation Bearer authorization can claim one connect-only - key. The client persists its generated secret before submitting it. - Retries must present that same secret; a different, rotated or revoked - credential is never replaced. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/machine/sandbox-node.mdx b/apps/docs/content/docs/api-reference/machine/sandbox-node.mdx deleted file mode 100644 index 7ab0fde2a..000000000 --- a/apps/docs/content/docs/api-reference/machine/sandbox-node.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Sandbox Node -description: >- - Sandbox Node. Machine connection API: Route-specific node enrollment, node, - daemon, or executor credential. Generated local machine contract. These - connections reach Core directly, never through Web. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Authenticates with an unconsumed enrollment token, or a retained node - credential with X-OAC-Node-ID. Does not consume the token or expose - E2B credentials. Node files cannot override this specification. - - content: >- - Node machine connection. Consumes a one-use enrollment token; grants - no project or administrator access. Responses contain only explicit - safe fields. core_url is required and must equal the installation - public URL; a different address gets 409 sandbox_node_address_mismatch - and leaves the token unused. - - content: >- - Node machine connection. Authenticates with the retained node - credential; grants no project or administrator access. Responses - contain only explicit safe fields. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/meta.json b/apps/docs/content/docs/api-reference/meta.json deleted file mode 100644 index f96a25397..000000000 --- a/apps/docs/content/docs/api-reference/meta.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "title": "Application API", - "pages": [ - "index", - "agents", - "environments", - "environment-templates", - "sessions", - "artifacts", - "events", - "items", - "subagents", - "turns", - "files", - "skills", - "vaults", - "credentials", - "core", - "machine" - ] -} diff --git a/apps/docs/content/docs/api-reference/sessions.mdx b/apps/docs/content/docs/api-reference/sessions.mdx deleted file mode 100644 index 64a9dbeb0..000000000 --- a/apps/docs/content/docs/api-reference/sessions.mdx +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: Sessions -description: >- - Sessions. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Cursor and results are scoped to the authenticated execution tenant; - an unknown, malformed or foreign after cursor returns not found. - Optional agent_id matches the immutable root Agent ID, including - inline Agents and historical Sessions whose saved source was updated - or deleted. Omission lists all Agents. Returns the same Environment - and pending-input activity projection as Session retrieval, including - self_hosted Sessions. - - content: >- - The optional Core model_provider bundle resolves from the Session - override, saved Agent defaults, then, for openai_hosted and none, the - deployment default of the resolved harness; self_hosted never uses the - deployment default and none accepts only it. openai_hosted and - self_hosted Sessions that resolve no bundle return 400 - model_provider_required with param x_agents_core.model_provider before - any write. Core encrypts and freezes the resolved bundle; later Agent - or deployment default edits and same-key retries cannot change it. - Keys are never returned. Supports inline configuration or a - tenant-owned saved agent_id with per-Session field replacements. - Execution supports model/instructions, text verbosity, non-deferred - function tools, adapter-qualified multi_agent with persisted Subagent - reads, implicit reasoning, service tier auto and environment type - none, subject to the configured engine. Codex additionally supports - HTTP MCP with service origin (omitted or null on HTTP transport is - saved as service), native allowed_tools and boolean required - defaulting to false. Session vault_ids attach only project-owned - Vaults; credential_id selects an attached static bearer or OAuth - credential for the exact HTTPS URL, while null/omission selects a - unique match or remains anonymous. Session reads, lists and event - snapshots show that implicitly selected credential ID in a null or - omitted credential_id, also after the credential is deleted; anonymous - selections stay null and the stored caller intent is unchanged. After - the input requirement and before any write, a credential_id without - vault_ids, one outside the attached Vaults (one message for missing, - foreign and unattached IDs) or one for another server_url returns 400 - invalid_request_error, and several implicit matches return 409 - conflict_error. Missing decryption configuration fails dispatch - without anonymous fallback. Required initialization uses native - startup before the first native Turn, including cold resume, and - requires a separately advertised capability; exact hosted creation - timing and error parity remain unverified. Explicit environment-origin - HTTP MCP is supported on managed and self-hosted workspaces through - the same Runtime bindings; native OAuth login remains unsupported. The - self_hosted profile uses a qualified native harness, a clean absolute - workspace_directory and optional absolute local capability_directories - prepared by Runtime, with optional non-deferred function tools and - HTTP MCP using explicit environment origin, optionally authenticated - by the attached Vault rules. Service-origin HTTP remains restricted to - service-side environment:none. Remote MCP and remote Bearer - authentication each require separately advertised combination support; - old peers cannot receive unsupported work. Omitted/null - capability_directories use the empty-list default; self_hosted - requires configured execution plus executor registry. Claude SDK - currently requires medium verbosity and object-root function schemas. - It supports anonymous or attached static-bearer service-origin HTTP - MCP on none with boolean required and separately advertised - MCP/bearer/required runtime support. Required servers must be - connected before the first native input is released; pending or failed - startup rejects execution. The shared Vault selection and immutable - binding rules apply; unsupported native labels/tool names reject - before persistence. An attached Vault with no matching credential may - remain anonymous; missing keys or failed credential lookup/decryption - never fall back to anonymous execution. Omitted stream defaults to - false; stream and agent_id cannot be null. Metadata may be null; - non-string values and limit violations return invalid_request_error - with a metadata or metadata. param. The inline agent uses the - Agent create configuration validation with agent.-prefixed params, - reported before the input requirement and saved-Agent lookup; saved - configurations with conflicting tools or schema roots reject admission - with the same errors, and execution limits keep - unsupported_or_invalid_configuration. Hosted network policy rejections - return invalid_request_error with a null param. Initial input accepts - a string or ordered user-message array. Codex and Claude SDK on none - and qualified managed or self_hosted workspace profiles also accept - inline PNG/JPEG image content; other image combinations and remote - URLs are unsupported. None initial input atomically starts a Turn; - self_hosted initial input is reserved while returning its Environment - connection target, with execution deferred to native readiness and - Session failure on initial timeout. Initial input is required for none - and for streamed creation outside self_hosted. Omitted/null input - remains valid for non-streaming hosted and self_hosted creation. With - stream=true, returns live Session events starting with the committed - creation snapshot and closes right after the first agent.session.idle - recorded when a Turn ends or an input reservation stops being pending, - or any agent.session.failed, without sending later events. A creation - that admitted nothing closes after the snapshot; a settlement that - records no event closes after events up to the cursor read with a - settled Session projection. Required actions keep it open; disconnect - does not cancel execution. The GET events stream remains live-only. - New Sessions retain their authenticated creator; all creation retries - require the same typed subject, including across key rotation. - Saved-Agent retries and inline requests using Vault attachments or - credential references retain caller intent independently of later - resource changes; new hosted inline requests also freeze caller intent - before deployment defaults resolve; unrelated non-hosted inline - retries preserve resolved/default equivalences, and their resolved - hash leaves out any deployment default. Provider keys enter retry - hashes only as fingerprints keyed by the credential key. Unknown - historical creators reject retries; known creators without recorded - intent retain resolved-snapshot retry rules. These conflict policies - are local and not verified hosted parity. A same-key stream=true retry - of an existing creation returns 201 with no events and closes at once; - retry with stream=false or use the GET events stream to recover. - Claude SDK on none, Core-managed Docker openai_hosted and self_hosted - supports qualified object-root json_schema output with medium - verbosity, single-Agent execution and ordinary functions. Hosted - execution reuses native workspace tools and Files/Artifacts; Skills, - Plugins, capability directories, HTTP MCP, Subagent and tool_search - combinations remain unqualified, including inherited template - contents. Other non-text initial input remains unsupported. Basic - Codex and Claude SDK openai_hosted creation requires an explicitly - configured managed provider. The Claude workspace profile supports - non-deferred function tools with text or successful inline PNG/JPEG - results alongside native workspace tools; explicit environment-origin - HTTP MCP uses the common Runtime path. MiniMax accepts public - environment-origin HTTP MCP only with null or omitted allowed_tools - and required=false; even an empty non-null allowlist rejects. Idle - Sessions provision automatically; initial provisioning has no caller - connection action. Network defaults to enabled; disabled and - restricted policies reject before compute allocation because the - current Runtime cannot enforce them. The x_agents_core.environment - extension accepts common preparation fields for either hosted or - self-hosted placement: environment_template_id, files, env, packages, - setup_commands, skills, plugins and capability_directories. Duplicate - fields in environment and the extension reject. Confidential env, - npm/Python packages and ordered setup commands use the same - Environment-owned initialization lifecycle; compute allocation does - not own preparation. Unknown side effects are not replayed after - disconnect or restart. System dependencies must be preinstalled in the - sandbox image or template, or on the host machine; packages.system is - rejected. Initial inline and tenant-owned file_id files freeze - encrypted bytes before provisioning, then install through the common - Core lifecycle before native execution or live Files access. With a - template reference, omitted/null files, env, packages and - setup_commands inherit. Non-null files and command lists replace; env - overlays by key; each package manager inherits on omission/null and - otherwise replaces its list. Empty lists clear their selected field. - Tenant-owned environment_template_id references inherit omitted/null - network and allow only narrowing overrides. Inline hosted network:null - retains the enabled default; updating a Template with network:null - resets its saved policy to enabled. Core freezes effective - configuration; template updates/deletion do not alter Session - snapshots or same-intent creation retries. Inline or tenant-owned - skill_reference Skills share initialization. Templates preserve - default/latest/explicit selectors; Session creation freezes concrete - metadata and encrypted content atomically. Skill, Plugin and - capability-directory list omission/null inherit; a non-null list - replaces, including empty-list clearing. Omitted/null Skill version - selectors resolve the default version. Source deletion/default updates - cannot change committed Session Skill contents. Deferred function - discovery uses type-only tool_search and per-function defer_loading in - the qualified single-agent Claude function profile on none or a - managed/user-owned workspace, including qualified inline image - messages and text results. Explicit web_search mode disabled and - programmatic_tool_calling enabled false use frozen common Runtime - controls. Enabled forms, including those saved on an Agent, remain - unqualified and reject before any write unless the Session replaces - tools. Omitted programmatic configuration preserves native behavior, a - documented difference from the official default-on behavior. Other - combinations remain unqualified; see the operation coverage. - - content: >- - Returns supported none, self_hosted and basic openai_hosted Session - environments. Self-hosted pending input can require a caller - connection before a Turn exists. Hosted initial provisioning remains - idle until a Turn starts; connection observations are not native - execution readiness. - - content: >- - The metadata field is required in an update body. Send null or {} to - clear it, or supply an object to replace all pairs. Up to 16 string - pairs, with keys at most 64 characters and values at most 512 - characters; violations and non-string values return - invalid_request_error with a metadata or metadata. param. U+0000 - is rejected as a local storage limit. Malformed, missing and foreign - Session IDs share the not-found response. Execution configuration and - activity are unchanged. Returns the same safe Environment and - pending-input activity projection as Session retrieval. - - content: >- - Removes a durably idle or failed Session and its history from the - public API. A Session whose root Turn is queued, in progress or - waiting (including required actions) or whose input reservation is - pending returns 409 conflict_error and is left unchanged; cancel it - and wait until it is idle before deleting. Subagent child Turns and - pending Environment file writes are not checked and do not block - deletion. Repeating the deletion of the caller's own deleted Session - returns the same confirmation; missing and foreign Sessions return - 404. Internal records and native history are retained pending separate - physical cleanup; overlapping stream timing remains unverified. - - content: >- - An empty events array is a resource-authorized no-op; it creates no - execution retry identity, Turn, Item or input receipt. For environment - none, atomically accepts text messages, cancellation and function - results. Messages steer active work or start a queued Turn. Qualified - Codex and Claude SDK workspace profiles accept text and inline - PNG/JPEG messages, independently of managed or self_hosted ownership. - Under the Session lock, matching retries retain their original target; - new active messages append to the current Turn, while idle messages - reserve work and wait up to the original five-minute - connection/admission deadline. Return 202 only after durable - admission, without claiming native application; active messages create - no Turn or reservation. Cancellation-only prepared-environment batches - use existing durable cancellation admission and return 202 without - waiting for native exit; a new cancellation conflicts while a pre-Turn - reservation is pending. Homogeneous tool_result-only - prepared-environment batches reuse existing scoped result admission - and application receipts without creating a Turn or bypassing a - pending reservation. Mixed prepared-environment batches remain - unsupported. HTTP expiry/cancellation use local 409 - environment_input_expired/environment_input_cancelled errors. New - input on a Session whose hosted Environment failed to provision - returns the observed 409 conflict_error "the hosted environment failed - to provision"; input already waiting when it fails and expired - Environments keep the local 409 environment_unavailable. Input the - Session cannot accept in its current state, such as a result after - cancellation or a batch while earlier input is pending, and a result - that differs from the call's saved result return 409 with type and - code conflict_error; reusing an Idempotency-Key with a different batch - returns the local 409 idempotency_conflict. Inside an owned Session, a - result for an unknown call or for a call of another Turn returns 400 - invalid_request_error and changes nothing; missing and foreign - Sessions return 404. Losing execution ownership returns 503. The - response write deadline accommodates the admission window for either - prepared Environment, independently of new-hosted-admission and - executor URL settings. Disconnecting the waiting HTTP request does not - cancel retained work or restart its deadline. Retry keys identify the - whole ordered batch. Function output accepts text or ordered - text/image parts subject to engine support; Claude SDK accepts text - results and, on none and qualified workspace profiles, successful - inline PNG/JPEG results, preserving ordered content; error images and - remote references reject before admission. Native image resizing may - change bytes. Runtime image-result support is checked only for - image-bearing delivery. Codex and Claude SDK on none and qualified - managed or self_hosted workspace profiles accept ordered inline - PNG/JPEG image messages. Other engines remain text-only; remote image - URLs are unsupported. Image references are retained unchanged without - service-side downloads. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills.mdx b/apps/docs/content/docs/api-reference/skills.mdx deleted file mode 100644 index 8757bc526..000000000 --- a/apps/docs/content/docs/api-reference/skills.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Skills -description: >- - Skills. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists tenant-owned metadata in timestamp order. Default page size 20, - maximum 100. Limit 0 returns an empty page whose has_more reports - whether any Skill follows the cursor; exact hosted defaults remain - unverified. - - content: >- - Accepts one ZIP in files or a directory in files[]. Applies the - qualified portable Skill bundle profile. No Beta header is required; - full hosted upload limits and activation extensions are not qualified. - - content: >- - Returns tenant-owned metadata without decrypting contents or starting - Runtime. No Beta header is required. - - content: >- - Changes only the tenant-owned default pointer; immutable versions and - existing Session snapshots remain unchanged. - - content: >- - Deletes tenant-owned source bundles. Existing Session installation - snapshots remain independent. - - content: >- - Downloads an authorized ZIP using the default pointer when no concrete - version is supplied. Exact upstream unversioned selection, content - headers and range semantics remain unverified. - - content: >- - Orders by version number; after identifies a version resource, not a - version number. An after value that does not begin with skillver, or a - version of another Skill, returns 400 invalid_value with param after; - a missing version returns not found. No contents are decrypted. Limit - 0 returns an empty page whose has_more reports whether any version - follows the cursor. - - content: >- - Deleting the only remaining version also deletes the Skill; existing - Session installation snapshots remain independent. The default version - cannot be deleted while other versions remain. Version numbers are - never reused. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/subagents.mdx b/apps/docs/content/docs/api-reference/subagents.mdx deleted file mode 100644 index e2f3346ee..000000000 --- a/apps/docs/content/docs/api-reference/subagents.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Subagents -description: >- - Subagents. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Includes nested and closed Subagents. Cursors are Subagents of the - same tenant and Session. Any other after value, including a malformed - one, returns 400 invalid_request_error with the message "Invalid - resource ID in `after`". A limit outside 1–100 is rejected. - - content: >- - Returns this Session's persisted Subagent. Active includes idle - between Turns. Resuming preserves opened_at and clears closed_at. - Unknown or inaccessible parent scopes return not found. - - content: >- - Returns only this Subagent's own Items across all its Turns, not its - descendants' Items. Cursors are Items of the same tenant, Session and - Subagent. Any other after value, including a malformed one, returns - 400 invalid_request_error with the message "Invalid session item ID in - `after`". - - content: >- - Includes this Subagent's Turns after resume, with the Session's Agent - ID as agent_id. Cursors are Turns of the same tenant, Session and - Subagent. Any other after value, including a malformed one, returns - 400 invalid_request_error with the message "Invalid resource ID in - `after`". Missing recorded usage remains null. A limit outside 1–100 - is rejected. - - content: >- - Returns a Turn owned by this Subagent. Its agent_id is the Session's - Agent ID and its subagent_id identifies the Subagent. Session Turn - routes do not return child Turns. Unknown or inaccessible parent - scopes return not found. - - content: >- - Returns Items owned by this exact Subagent Turn. Cursors are Items of - the same tenant, Session, Subagent and Turn. Any other after value, - including a malformed one, returns 400 invalid_request_error with the - message "Invalid session item ID in `after`". ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/turns.mdx b/apps/docs/content/docs/api-reference/turns.mdx deleted file mode 100644 index e3dac307c..000000000 --- a/apps/docs/content/docs/api-reference/turns.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Turns -description: >- - Turns. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Returns the Session's root Turns in creation order; Subagent Turns are - listed through the Subagent Turn routes. The cursor belongs to the - same Session and tenant; any other after value, including a malformed - one or a Subagent Turn ID, returns not found. Usage contains the - latest recorded complete token breakdown; missing measurements remain - null. - - content: >- - Returns a root Turn of this Session. A Subagent Turn ID returns the - same not found error as a missing Turn; read it through the Subagent - Turn routes. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/vaults.mdx b/apps/docs/content/docs/api-reference/vaults.mdx deleted file mode 100644 index 3bb1698f4..000000000 --- a/apps/docs/content/docs/api-reference/vaults.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Vaults -description: >- - Vaults. Application API: Project API key. Public schema constrained by the - pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core - extensions. -full: true -_openapi: - toc: [] - structuredData: - headings: [] - contents: - - content: >- - Lists project-owned Vaults independently of execution. An unknown, - malformed or foreign after cursor returns not found. Includes active - and archived records by default. Status accepts a scalar, the SDK's - status[] array or both, filtering by their union; a repeated scalar is - rejected. Limits default to 20 and clamp to 1–100. Equal creation - times use ID ordering; exact hosted errors and concurrent-page - behavior remain unverified. Archive/delete lifecycle is not - implemented. - - content: >- - Creates a project-owned Vault independently of execution. Omitted name - stays null; a supplied string is trimmed and must contain 1–256 UTF-8 - bytes. Explicit null name is invalid. Omitted/null metadata becomes an - empty object; non-string values return invalid_request_error with a - metadata. param. Metadata has a local 64 KiB encoded storage - bound. U+0000 in stored strings is rejected as a local storage limit. - Credentials, Session binding and hosted error/retry parity remain - incomplete. - - content: >- - Reads a Vault owned by the authenticated project without resolving - credentials, Sessions or execution devices. Missing and foreign IDs - share the same not-found response; exact hosted error semantics remain - unverified. - - content: >- - Atomically removes the authenticated project's Vault and all its - stored Credentials without an encryption key, decryption or external - requests. Existing Session snapshots, history and recorded retries - retain their frozen identities; subsequent credential lookups fail - without reselection or anonymous fallback. Already-resolved tokens and - running Sessions are not revoked or cancelled. Missing/repeated - deletion locally returns 404. Exact hosted archive, post-delete - visibility and concurrent/error semantics remain unverified; physical - erasure from native history, WAL or backups is not established. ---- - -{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} - - \ No newline at end of file diff --git a/apps/docs/content/docs/bootstrap-projects-keys.mdx b/apps/docs/content/docs/bootstrap-projects-keys.mdx deleted file mode 100644 index 529695e3d..000000000 --- a/apps/docs/content/docs/bootstrap-projects-keys.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "Sign in and issue application keys" -description: "Keep the Core key on the management side and issue Project API keys through Web." ---- - -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. - -## Request boundary - -```mermaid -flowchart LR - browser["Administrator browser"] - console["Console server"] - core["Core"] - database[("PostgreSQL")] - application["Application / official SDK"] - machine["Nodes and Runtime daemons"] - installer["Installer domain service"] - - browser -->|"same origin: /console/*, /core/v1/*; session cookie"| console - console -->|"/core/v1/* with the Core key"| core - console -->|"domain setup, Unix socket"| installer - application -->|"/v1 with a Project API key"| core - machine -->|"/api/v1 with machine credentials"| core - core <--> database -``` - -The deployment's reverse proxy routes `/v1` and `/api/v1` to Core and every other path to the console; the [installation options](/install-options#https-and-the-reverse-proxy) gives the routes. The console handles each path as follows: - -| Path | Sign-in | Handling | -| --- | --- | --- | -| `/healthz` | No | `GET` or `HEAD` answers `200 ok` | -| `/v1`, `/api/v1` and below | — | 404, whatever credential the request carries | -| `/node-install/*` | No | The node installation payload (see [Node installation payload](#node-installation-payload)) | -| `/console/auth`, `/console/auth/login`, `/console/auth/logout` | No | [Sign-in](#sign-in) | -| `/`, `/index.html`, `/favicon.svg`, `/oac-mark.svg`, `/assets/*` | No | Static console assets | -| `/console/config` | Yes | [Console configuration](#console-configuration) | -| `/console/installation/domain` | Yes | [Domain setup](#domain-setup) | -| `/core/v1/*` | Yes | [Forwarded to Core](#forwarding-to-core) | -| `/core` and other paths under `/core/` | Yes | 404 | -| Any other path | Yes | Static assets; a path without a file extension falls back to `index.html` | - -Every request except `/healthz`, `/v1` and `/api/v1` must pass these checks first: - -1. **Host and origin.** The `Host` header must equal the host of `OAC_WEB_ORIGIN`. An `Origin` header, when present, must equal that origin, and `Sec-Fetch-Site` must be `same-origin` or `none`. A write that carries neither `Origin` nor `Sec-Fetch-Site: same-origin` needs a same-origin `Referer`. Otherwise the console answers 403. `/node-install/*` checks only the host and the path. -2. **Safe request.** The path must start with `/` and contain no `%`, backslash, NUL, dot segment or empty segment. Absolute-form request targets, `CONNECT`, `TRACE` and any request with an `Upgrade` header get 400. A request can therefore never leave `/core/v1` on Core, and the console carries no WebSocket. -3. **Sign-in.** Paths that need sign-in answer 401 without a valid session cookie. - -Under `/core`, these failures use the Core error envelope with the codes in [console-generated failures](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md#console-generated-failures); elsewhere they return `{"error": "…"}`, or plain text for an unsafe request. Every response carries `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer` and `Content-Security-Policy: frame-ancestors 'none'`. - -## Forwarding to Core - -The console forwards each signed-in `/core/v1/*` request by prefix to `OAC_WEB_UPSTREAM`, with its path and query unchanged. Core alone decides whether the route exists, and its responses and errors pass through unchanged. The console therefore needs no change when Core adds a `/core/v1` route. - -On the way to Core, the console: - -- removes the browser's `Authorization`, `Proxy-Authorization`, `Cookie`, `Origin` and `Referer` headers; -- sends `Authorization: Bearer `; -- sets `X-Core-Console-Actor: console`, replacing any value the browser sent. Core records it as a display-only audit label ([administrator API](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/admin-api.md)); -- ignores ambient HTTP proxy settings, so the Core key reaches only the configured Core; -- streams responses without buffering. - -On the way back, it removes `Set-Cookie`, `WWW-Authenticate`, `Location`, `Refresh` and every `Access-Control-*` header. A redirect from Core, or a failed connection to Core, becomes 502 `core_unreachable`. - -The console never retries a request. Browser code calls `/core/v1` through the typed clients in [`packages/agents-client`](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/packages/agents-client/README.md); [console API usage](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/console-api-usage.md) lists what each page reads and writes. - -## Sign-in - -| Method and route | Request | Result | -| --- | --- | --- | -| `GET /console/auth` | No body | `200 {"mode":"login"}` or `200 {"mode":"authenticated"}` | -| `POST /console/auth/login` | `Content-Type: application/json`; body `{"core_key":"…"}` with no other member, at most 4 KiB | `200 {"mode":"authenticated"}` and the session cookie | -| `POST /console/auth/logout` | No body | `200 {"mode":"login"}`; ends the session and clears the cookie | - -The administrator signs in with the deployment's [Core key](/troubleshooting#core-key). There are no console accounts, usernames or setup step, and signing in grants the whole console. - -- The console compares SHA-256 digests of the submitted and configured keys in constant time. It never logs or returns the key. -- The session cookie `core_console_session` is HttpOnly, `SameSite=Strict`, and `Secure` when `OAC_WEB_ORIGIN` is HTTPS. It lasts 12 hours. -- Sessions live only in the console's memory, at most 64 at a time; the oldest is dropped first. A console restart or a Core key rotation signs everyone out. -- At most two sign-in checks run at once; another attempt gets 429 with `Retry-After: 1`. -- Failed attempts share a budget of 10 per minute; beyond it, a wrong key gets 429 with `Retry-After: 60`. The correct key always signs in, which is why the console refuses to start with a Core key shorter than 32 characters. - -Sign-in errors: 400 for a malformed body, 401 `Invalid Core key`, 405 for a method other than `POST`, 415 for a body that is not JSON, 429 as above, and 503 when the console cannot create a session. - -## Console configuration - -`GET /console/config` returns what the signed-in browser needs to add nodes: - -| Field | Meaning | -| --- | --- | -| `node_installer` | Whether the console serves a node installation payload | -| `node_installer_sha256` | SHA-256 of that payload's `node-install.pyz`; Add node commands verify it before running the installer | -| `node_artifacts` | The providers (`docker`, `microsandbox`) whose node artifacts the payload holds, locally or as a pinned release download. Read on every request, so artifacts added by rerunning the installer appear without a restart | - -## Node installation payload - -With `OAC_WEB_NODE_PAYLOAD_DIR` set, the console serves the matched distribution's node payload at `/node-install/` without sign-in: `node-install.pyz`, `manifest.json`, `SHA256SUMS`, `runtime/seccomp.json`, and the node artifacts the manifest declares under `artifacts/`. An artifact missing locally redirects (307) to its pinned release download. Node install and uninstall commands download from `/node-install/`, so the reverse proxy must send that path to the console. Nodes verify every checksum themselves. - -## Domain setup - -`GET` and `POST /console/installation/domain` let **System → Domain and HTTPS** configure a managed installation's domain. They are console routes, not Core routes. After the same origin and sign-in checks, the console passes the request body (at most 2 KiB) to the installer's Unix socket at `OAC_WEB_INSTALLATION_SOCKET`, authenticated with the Core key, and returns the installer's JSON answer and status. The request times out after 20 seconds. - -| Method | Request | Result | -| --- | --- | --- | -| `GET` | No body | The domain status | -| `POST` | `{"hostname":"core.example.com"}`, optionally with `"confirm_public_url_change":"https://core.example.com"` | 202 and the status; the installer checks and applies the domain in the background | - -The status has `supported`, `state` (`unconfigured`, `checking`, `applying`, `ready` or `failed`), and nullable `public_url`, `target_url` and `message`. Installer errors use `{"error":{"code":"…","message":"…"}}`. Changing an address that nodes or executors already use returns 409 `public_url_confirmation_required` until the request confirms the new URL; pending `config.json` edits, an installation that is not applied or not running, hand-edited generated files, and another installation operation holding the lock (`installation_busy`) also return 409. - -Without `OAC_WEB_INSTALLATION_SOCKET` (external reverse proxy installations), `GET` reports `supported: false` and `POST` returns 400 `domain_setup_unavailable`. An unreachable installer or an invalid answer returns 502 `installation_unreachable`. - -The System page submits a hostname once, polls the status every 2 seconds while it is `checking` or `applying`, and asks for confirmation when the installer requires it. It never retries a write. Applying the domain restarts the console, which ends every session; the page keeps a sign-in link to the new HTTPS address. Only the `ready` state confirms HTTPS; the browser does not probe the new origin. The installer owns certificates, locking and recovery ([managed HTTPS](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/deploy/install/README.md#managed-https)). - -`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](/configure#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: - -1. `GET /healthz` on the console and on Core. Each proves only that the process answers. -2. Sign in, then read `GET /core/v1/projects` in the browser. This proves the browser-to-console and console-to-Core path and the console's Core key. -3. A Project API key works on `/v1` and fails on `/core/v1`. The Core key fails on `/v1`, and `/v1` sent to the console answers 404. -4. A cross-origin write to the console is rejected, and a forged `X-Core-Console-Actor` header does not change the audit label. -5. Neither sign-in nor the sandbox deployment read (`GET /core/v1/sandbox/deployment`) proves that a model or a sandbox is ready. Runtime observations and history report execution separately. - -A sign-in failure belongs to the console. A 401 from Core on a signed-in request means the console's Core key does not match Core's digest, or the console reaches the wrong Core. The [troubleshooting table](/troubleshooting#troubleshooting) covers the common symptoms. - -[Repository source](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/console-server.md) diff --git a/apps/docs/content/docs/concepts.mdx b/apps/docs/content/docs/concepts.mdx deleted file mode 100644 index ef0c0da2e..000000000 --- a/apps/docs/content/docs/concepts.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Concepts and ownership" -description: "Projects, credentials and the boundary between applications, administration and execution." ---- - -OpenAgentCore implements the OpenAI Agents API under the -[public API rules](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/AGENTS.md#public-api). - -## Three namespaces, three credentials - -Applications, administrators and machines each use their own namespace and -credential. The [API index](/public-api) 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](/troubleshooting#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](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/AGENTS.md#design-principles) and the -[Core–Runtime protocol](/runtime-protocol). - -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](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/native-error-classification.md). - -[Repository source](https://github.com/MiniMax-AI/OpenAgentCore/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/design-principles.md) diff --git a/apps/docs/content/docs/configure.mdx b/apps/docs/content/docs/configure.mdx deleted file mode 100644 index 25eac36a0..000000000 --- a/apps/docs/content/docs/configure.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Configuration reference" -description: "The operator config.json, generated files and database-owned runtime settings." ---- - -Every setting of a Core installation has exactly one home. There are two kinds: - -| Kind | Examples | Home | Change it with | Takes effect | -| --- | --- | --- | --- | --- | -| [Process settings](#process-settings-configjson) | Public URL, ports, logging, harnesses, execution concurrency, audit retention, OAuth origins, database pool, Runtime history export | `config.json` in the installation directory (default `~/.oac/core`) | Web domain setup or `oac domain` for managed HTTPS; otherwise edit the file, then run `oac apply` | `oac apply` restarts the services that read the changed settings | -| [Runtime settings](#runtime-settings-web) | Sandbox backend and size, nodes, Projects and keys, default models, executor credentials | Core's PostgreSQL database | Web, or the Core API (`/core/v1`) with the Core key | Saved without a Core restart; nodes prepare Runtime changes asynchronously | - -Web's **System** page shows the installation's addresses, the default models, the sandbox configuration and, under **Startup settings**, the process settings read-only with the path of `config.json` and the apply command. Secrets live in [`secrets/`](#installation-directory), one copy each. The files in `generated/` are derived from `config.json`. No configuration file defines Projects or API keys. - -## Process settings: config.json - -The installer writes every setting that applies to the installation's [mode](/install-options#modes), so the file shows each value. Installer flags listed in [installation options](/install-options) only seed it. To change a setting, edit the file and apply it: - -```sh -~/.oac/core/oac apply --dry-run # show the changed settings, files and restarts -~/.oac/core/oac apply -``` - -### How oac apply works - -1. It validates `config.json` and changes nothing if a value is invalid. `mode`, `native_core` and `ingress` are fixed after installation; to change them, install into a new directory. -2. It writes the files Core, Web and Compose read into `generated/`: `compose.json`, `core.env`, `core-key-digests.json`, `settings.json` and, when used, `runtime-history.json`, the managed `Caddyfile` and the native Core unit. Don't edit them. A generated file edited by hand stops `apply` until you move the change into `config.json` and run `oac apply --discard-edits`, which keeps the edited copy as `generated/.edited-