diff --git a/apps/docs/app/[[...slug]]/page.tsx b/apps/docs/app/[[...slug]]/page.tsx index ce9b7c35f..e50932d01 100644 --- a/apps/docs/app/[[...slug]]/page.tsx +++ b/apps/docs/app/[[...slug]]/page.tsx @@ -22,7 +22,7 @@ export default async function DocsPageRoute({ const MDX = page.data.body return ( - + {page.data.title} {page.data.description} diff --git a/apps/docs/app/global.css b/apps/docs/app/global.css index cc12ffffa..cf3065e23 100644 --- a/apps/docs/app/global.css +++ b/apps/docs/app/global.css @@ -101,3 +101,21 @@ body { ::selection { background: color-mix(in srgb, var(--color-fd-primary) 22%, transparent); } + +/* A folded operation description: the contract's full prose stays on the page + without pushing the request and response sections below the fold. */ +.prose details.api-details { + margin: 1rem 0; + padding: 0.25rem 0.75rem; + border: 1px solid var(--color-fd-border); + border-radius: 0.5rem; + background: color-mix(in srgb, var(--color-fd-muted) 35%, transparent); +} + +.prose details.api-details > summary { + padding: 0.35rem 0; + color: var(--color-fd-muted-foreground); + font-size: 0.8125rem; + font-weight: 600; + cursor: pointer; +} diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx index a14a4972e..02bb568e8 100644 --- a/apps/docs/app/layout.tsx +++ b/apps/docs/app/layout.tsx @@ -16,7 +16,16 @@ export default function RootLayout({ children }: { children: ReactNode }) { - {children} + + {children} + diff --git a/apps/docs/components/api-page.tsx b/apps/docs/components/api-page.tsx index 3976f2a65..02417a3c7 100644 --- a/apps/docs/components/api-page.tsx +++ b/apps/docs/components/api-page.tsx @@ -9,5 +9,15 @@ export async function APIPage({ ...props }: Omit & { document: string }) { // References never collect credentials or dispatch requests from the browser. - return + // Response schemas are shown in full; generating a TypeScript copy of every + // response for every status compiled the same schemas again and was about + // half of each page's render time. + return ( + + ) } 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/agents/create-a-reusable-agent.mdx b/apps/docs/content/docs/api-reference/agents/create-a-reusable-agent.mdx new file mode 100644 index 000000000..e914e32b6 --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/create-a-reusable-agent.mdx @@ -0,0 +1,53 @@ +--- +title: Create a reusable Agent +description: Persists configuration independently of execution. +full: true +_openapi: + method: POST + route: /agents + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/agents/delete-a-reusable-agent.mdx b/apps/docs/content/docs/api-reference/agents/delete-a-reusable-agent.mdx new file mode 100644 index 000000000..8895235e5 --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/delete-a-reusable-agent.mdx @@ -0,0 +1,23 @@ +--- +title: Delete a reusable Agent +description: Deletes only the authenticated tenant's saved configuration. +full: true +_openapi: + method: DELETE + route: /agents/{agent_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/agents/index.mdx b/apps/docs/content/docs/api-reference/agents/index.mdx new file mode 100644 index 000000000..5037ad008 --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/index.mdx @@ -0,0 +1,14 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List reusable Agents](/api-reference/agents/list-reusable-agents) | `GET` | `/v1/agents` | +| [Create a reusable Agent](/api-reference/agents/create-a-reusable-agent) | `POST` | `/v1/agents` | +| [Retrieve a reusable Agent](/api-reference/agents/retrieve-a-reusable-agent) | `GET` | `/v1/agents/{agent_id}` | +| [Update a reusable Agent](/api-reference/agents/update-a-reusable-agent) | `POST` | `/v1/agents/{agent_id}` | +| [Delete a reusable Agent](/api-reference/agents/delete-a-reusable-agent) | `DELETE` | `/v1/agents/{agent_id}` | diff --git a/apps/docs/content/docs/api-reference/agents/list-reusable-agents.mdx b/apps/docs/content/docs/api-reference/agents/list-reusable-agents.mdx new file mode 100644 index 000000000..28d1748d1 --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/list-reusable-agents.mdx @@ -0,0 +1,23 @@ +--- +title: List reusable Agents +description: Lists only the authenticated tenant's saved Agents, independently of Sessions. +full: true +_openapi: + method: GET + route: /agents + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/agents/meta.json b/apps/docs/content/docs/api-reference/agents/meta.json new file mode 100644 index 000000000..2c156db2b --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Agents", + "pages": [ + "list-reusable-agents", + "create-a-reusable-agent", + "retrieve-a-reusable-agent", + "update-a-reusable-agent", + "delete-a-reusable-agent" + ] +} diff --git a/apps/docs/content/docs/api-reference/agents/retrieve-a-reusable-agent.mdx b/apps/docs/content/docs/api-reference/agents/retrieve-a-reusable-agent.mdx new file mode 100644 index 000000000..1608a3dfc --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/retrieve-a-reusable-agent.mdx @@ -0,0 +1,19 @@ +--- +title: Retrieve a reusable Agent +description: Reads the saved resource owned by the authenticated tenant, independently of execution Sessions. +full: true +_openapi: + method: GET + route: /agents/{agent_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Reads the saved resource owned by the authenticated tenant, independently of execution + Sessions. +--- + +{/* 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/agents/update-a-reusable-agent.mdx b/apps/docs/content/docs/api-reference/agents/update-a-reusable-agent.mdx new file mode 100644 index 000000000..37e2003bf --- /dev/null +++ b/apps/docs/content/docs/api-reference/agents/update-a-reusable-agent.mdx @@ -0,0 +1,33 @@ +--- +title: Update a reusable Agent +description: Preserves omitted fields and replaces supplied fields using shared saved-configuration validation. +full: true +_openapi: + method: POST + route: /agents/{agent_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ 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/artifacts/delete-a-published-artifact.mdx b/apps/docs/content/docs/api-reference/artifacts/delete-a-published-artifact.mdx new file mode 100644 index 000000000..febeb679e --- /dev/null +++ b/apps/docs/content/docs/api-reference/artifacts/delete-a-published-artifact.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a published artifact +description: Deletes the published copy without modifying its original workspace file. +full: true +_openapi: + method: DELETE + route: /agents/sessions/{session_id}/artifacts/{artifact_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Deletes the published copy without modifying its original workspace file. Already admitted + content reads may finish; later reads reject. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Already admitted content reads may finish; later reads reject. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/artifacts/download-immutable-artifact-bytes.mdx b/apps/docs/content/docs/api-reference/artifacts/download-immutable-artifact-bytes.mdx new file mode 100644 index 000000000..82d95661d --- /dev/null +++ b/apps/docs/content/docs/api-reference/artifacts/download-immutable-artifact-bytes.mdx @@ -0,0 +1,23 @@ +--- +title: Download immutable artifact bytes +description: >- + Streams stored bytes after tenant and Session authorization, including after Environment + expiration. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/artifacts/{artifact_id}/content + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Exact upstream headers and Range behavior remain unverified. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/artifacts/index.mdx b/apps/docs/content/docs/api-reference/artifacts/index.mdx new file mode 100644 index 000000000..66ed693f6 --- /dev/null +++ b/apps/docs/content/docs/api-reference/artifacts/index.mdx @@ -0,0 +1,13 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List immutable Session artifacts](/api-reference/artifacts/list-immutable-session-artifacts) | `GET` | `/v1/agents/sessions/{session_id}/artifacts` | +| [Retrieve immutable artifact metadata](/api-reference/artifacts/retrieve-immutable-artifact-metadata) | `GET` | `/v1/agents/sessions/{session_id}/artifacts/{artifact_id}` | +| [Delete a published artifact](/api-reference/artifacts/delete-a-published-artifact) | `DELETE` | `/v1/agents/sessions/{session_id}/artifacts/{artifact_id}` | +| [Download immutable artifact bytes](/api-reference/artifacts/download-immutable-artifact-bytes) | `GET` | `/v1/agents/sessions/{session_id}/artifacts/{artifact_id}/content` | diff --git a/apps/docs/content/docs/api-reference/artifacts/list-immutable-session-artifacts.mdx b/apps/docs/content/docs/api-reference/artifacts/list-immutable-session-artifacts.mdx new file mode 100644 index 000000000..21da7a353 --- /dev/null +++ b/apps/docs/content/docs/api-reference/artifacts/list-immutable-session-artifacts.mdx @@ -0,0 +1,32 @@ +--- +title: List immutable Session artifacts +description: Lists published outputs independently of Environment availability. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/artifacts + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/artifacts/meta.json b/apps/docs/content/docs/api-reference/artifacts/meta.json new file mode 100644 index 000000000..1e61c0a2c --- /dev/null +++ b/apps/docs/content/docs/api-reference/artifacts/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Artifacts", + "pages": [ + "list-immutable-session-artifacts", + "retrieve-immutable-artifact-metadata", + "delete-a-published-artifact", + "download-immutable-artifact-bytes" + ] +} diff --git a/apps/docs/content/docs/api-reference/artifacts/retrieve-immutable-artifact-metadata.mdx b/apps/docs/content/docs/api-reference/artifacts/retrieve-immutable-artifact-metadata.mdx new file mode 100644 index 000000000..3e68b5b4b --- /dev/null +++ b/apps/docs/content/docs/api-reference/artifacts/retrieve-immutable-artifact-metadata.mdx @@ -0,0 +1,16 @@ +--- +title: Retrieve immutable artifact metadata +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/artifacts/{artifact_id} + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/administrator-projects/archive-a-project-and-revoke-all-its-keys-while-retaining-assets.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/archive-a-project-and-revoke-all-its-keys-while-retaining-assets.mdx new file mode 100644 index 000000000..c94d5c1dc --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/archive-a-project-and-revoke-all-its-keys-while-retaining-assets.mdx @@ -0,0 +1,16 @@ +--- +title: Archive a Project and revoke all its keys while retaining assets +full: true +_openapi: + method: POST + route: /core/v1/projects/{project_id}/archive + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/create-an-empty-independent-project.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/create-an-empty-independent-project.mdx new file mode 100644 index 000000000..6a477fa94 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/create-an-empty-independent-project.mdx @@ -0,0 +1,16 @@ +--- +title: Create an empty independent Project +full: true +_openapi: + method: POST + route: /core/v1/projects + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/index.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/index.mdx new file mode 100644 index 000000000..df7f03ace --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/index.mdx @@ -0,0 +1,16 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Projects and active key counts](/api-reference/core/administrator-projects/list-projects-and-active-key-counts) | `GET` | `/core/v1/projects` | +| [Create an empty independent Project](/api-reference/core/administrator-projects/create-an-empty-independent-project) | `POST` | `/core/v1/projects` | +| [Rename a Project](/api-reference/core/administrator-projects/rename-a-project) | `POST` | `/core/v1/projects/{project_id}` | +| [Archive a Project and revoke all its keys while retaining assets](/api-reference/core/administrator-projects/archive-a-project-and-revoke-all-its-keys-while-retaining-assets) | `POST` | `/core/v1/projects/{project_id}/archive` | +| [List safe key metadata for a Project](/api-reference/core/administrator-projects/list-safe-key-metadata-for-a-project) | `GET` | `/core/v1/projects/{project_id}/keys` | +| [Issue an independent secret in an existing Project](/api-reference/core/administrator-projects/issue-an-independent-secret-in-an-existing-project) | `POST` | `/core/v1/projects/{project_id}/keys` | +| [Revoke one Project key while retaining shared assets](/api-reference/core/administrator-projects/revoke-one-project-key-while-retaining-shared-assets) | `DELETE` | `/core/v1/projects/{project_id}/keys/{key_id}` | diff --git a/apps/docs/content/docs/api-reference/core/administrator-projects/issue-an-independent-secret-in-an-existing-project.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/issue-an-independent-secret-in-an-existing-project.mdx new file mode 100644 index 000000000..587d44cd8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/issue-an-independent-secret-in-an-existing-project.mdx @@ -0,0 +1,16 @@ +--- +title: Issue an independent secret in an existing Project +full: true +_openapi: + method: POST + route: /core/v1/projects/{project_id}/keys + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/list-projects-and-active-key-counts.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/list-projects-and-active-key-counts.mdx new file mode 100644 index 000000000..14599e8f7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/list-projects-and-active-key-counts.mdx @@ -0,0 +1,16 @@ +--- +title: List Projects and active key counts +full: true +_openapi: + method: GET + route: /core/v1/projects + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/list-safe-key-metadata-for-a-project.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/list-safe-key-metadata-for-a-project.mdx new file mode 100644 index 000000000..7e826912f --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/list-safe-key-metadata-for-a-project.mdx @@ -0,0 +1,16 @@ +--- +title: List safe key metadata for a Project +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/keys + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/meta.json b/apps/docs/content/docs/api-reference/core/administrator-projects/meta.json new file mode 100644 index 000000000..7f115f309 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Administrator Projects", + "pages": [ + "list-projects-and-active-key-counts", + "create-an-empty-independent-project", + "rename-a-project", + "archive-a-project-and-revoke-all-its-keys-while-retaining-assets", + "list-safe-key-metadata-for-a-project", + "issue-an-independent-secret-in-an-existing-project", + "revoke-one-project-key-while-retaining-shared-assets" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/administrator-projects/rename-a-project.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/rename-a-project.mdx new file mode 100644 index 000000000..a4f4dc1d5 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/rename-a-project.mdx @@ -0,0 +1,16 @@ +--- +title: Rename a Project +full: true +_openapi: + method: POST + route: /core/v1/projects/{project_id} + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/revoke-one-project-key-while-retaining-shared-assets.mdx b/apps/docs/content/docs/api-reference/core/administrator-projects/revoke-one-project-key-while-retaining-shared-assets.mdx new file mode 100644 index 000000000..b1b7ed4c9 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/administrator-projects/revoke-one-project-key-while-retaining-shared-assets.mdx @@ -0,0 +1,16 @@ +--- +title: Revoke one Project key while retaining shared assets +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/keys/{key_id} + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/agents/delete-a-reusable-agent-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/agents/delete-a-reusable-agent-in-a-project.mdx new file mode 100644 index 000000000..656f30e42 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/agents/delete-a-reusable-agent-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a reusable Agent in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/agents/{agent_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/agents/index.mdx b/apps/docs/content/docs/api-reference/core/agents/index.mdx new file mode 100644 index 000000000..365337b23 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/agents/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List reusable Agents in a Project](/api-reference/core/agents/list-reusable-agents-in-a-project) | `GET` | `/core/v1/projects/{project_id}/agents` | +| [Retrieve a reusable Agent in a Project](/api-reference/core/agents/retrieve-a-reusable-agent-in-a-project) | `GET` | `/core/v1/projects/{project_id}/agents/{agent_id}` | +| [Delete a reusable Agent in a Project](/api-reference/core/agents/delete-a-reusable-agent-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/agents/{agent_id}` | diff --git a/apps/docs/content/docs/api-reference/core/agents/list-reusable-agents-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/agents/list-reusable-agents-in-a-project.mdx new file mode 100644 index 000000000..b9d153ec7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/agents/list-reusable-agents-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List reusable Agents in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/agents + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/agents/meta.json b/apps/docs/content/docs/api-reference/core/agents/meta.json new file mode 100644 index 000000000..79754b5f3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/agents/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Agents", + "pages": [ + "list-reusable-agents-in-a-project", + "retrieve-a-reusable-agent-in-a-project", + "delete-a-reusable-agent-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/agents/retrieve-a-reusable-agent-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/agents/retrieve-a-reusable-agent-in-a-project.mdx new file mode 100644 index 000000000..f51a52c67 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/agents/retrieve-a-reusable-agent-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve a reusable Agent in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/agents/{agent_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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/artifacts/delete-a-published-artifact-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/artifacts/delete-a-published-artifact-in-a-project.mdx new file mode 100644 index 000000000..772418363 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/artifacts/delete-a-published-artifact-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a published artifact in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/sessions/{session_id}/artifacts/{artifact_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/artifacts/download-immutable-artifact-bytes-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/artifacts/download-immutable-artifact-bytes-in-a-project.mdx new file mode 100644 index 000000000..796e20316 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/artifacts/download-immutable-artifact-bytes-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Download immutable artifact bytes in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/artifacts/{artifact_id}/content + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/artifacts/index.mdx b/apps/docs/content/docs/api-reference/core/artifacts/index.mdx new file mode 100644 index 000000000..a1e0d4840 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/artifacts/index.mdx @@ -0,0 +1,13 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List immutable Session artifacts in a Project](/api-reference/core/artifacts/list-immutable-session-artifacts-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/artifacts` | +| [Retrieve immutable artifact metadata in a Project](/api-reference/core/artifacts/retrieve-immutable-artifact-metadata-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/artifacts/{artifact_id}` | +| [Delete a published artifact in a Project](/api-reference/core/artifacts/delete-a-published-artifact-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/sessions/{session_id}/artifacts/{artifact_id}` | +| [Download immutable artifact bytes in a Project](/api-reference/core/artifacts/download-immutable-artifact-bytes-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/artifacts/{artifact_id}/content` | diff --git a/apps/docs/content/docs/api-reference/core/artifacts/list-immutable-session-artifacts-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/artifacts/list-immutable-session-artifacts-in-a-project.mdx new file mode 100644 index 000000000..9856f86e4 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/artifacts/list-immutable-session-artifacts-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List immutable Session artifacts in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/artifacts + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/artifacts/meta.json b/apps/docs/content/docs/api-reference/core/artifacts/meta.json new file mode 100644 index 000000000..69f22ced7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/artifacts/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Artifacts", + "pages": [ + "list-immutable-session-artifacts-in-a-project", + "retrieve-immutable-artifact-metadata-in-a-project", + "delete-a-published-artifact-in-a-project", + "download-immutable-artifact-bytes-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/artifacts/retrieve-immutable-artifact-metadata-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/artifacts/retrieve-immutable-artifact-metadata-in-a-project.mdx new file mode 100644 index 000000000..23e95718e --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/artifacts/retrieve-immutable-artifact-metadata-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve immutable artifact metadata in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/artifacts/{artifact_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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/core-administration/index.mdx b/apps/docs/content/docs/api-reference/core/core-administration/index.mdx new file mode 100644 index 000000000..6d335f9ac --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/index.mdx @@ -0,0 +1,16 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Query committed administrator mutations](/api-reference/core/core-administration/query-committed-administrator-mutations) | `GET` | `/core/v1/audit-log` | +| [Retrieve installation facts and process settings](/api-reference/core/core-administration/retrieve-installation-facts-and-process-settings) | `GET` | `/core/v1/installation` | +| [Retrieve Core operational metrics](/api-reference/core/core-administration/retrieve-core-operational-metrics) | `GET` | `/core/v1/metrics` | +| [Retrieve a managed Session's resource cleanup state](/api-reference/core/core-administration/retrieve-a-managed-session-s-resource-cleanup-state) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/archive` | +| [Release a managed Session's execution resources while retaining history](/api-reference/core/core-administration/release-a-managed-session-s-execution-resources-while-retaining-history) | `POST` | `/core/v1/projects/{project_id}/sessions/{session_id}/archive` | +| [List Runtime observations across managed Projects](/api-reference/core/core-administration/list-runtime-observations-across-managed-projects) | `GET` | `/core/v1/sandbox/runtime-observations` | +| [Summarize resource counts and Session usage by Project, Agent or creator key](/api-reference/core/core-administration/summarize-resource-counts-and-session-usage-by-project-agent-or-creator-key) | `GET` | `/core/v1/summary` | diff --git a/apps/docs/content/docs/api-reference/core/core-administration/list-runtime-observations-across-managed-projects.mdx b/apps/docs/content/docs/api-reference/core/core-administration/list-runtime-observations-across-managed-projects.mdx new file mode 100644 index 000000000..a47a15493 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/list-runtime-observations-across-managed-projects.mdx @@ -0,0 +1,23 @@ +--- +title: List Runtime observations across managed Projects +description: Core key only. Each observation is labelled with its owning Project ID. +full: true +_openapi: + method: GET + route: /core/v1/sandbox/runtime-observations + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration/meta.json b/apps/docs/content/docs/api-reference/core/core-administration/meta.json new file mode 100644 index 000000000..aea6a88cd --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Core Administration", + "pages": [ + "query-committed-administrator-mutations", + "retrieve-installation-facts-and-process-settings", + "retrieve-core-operational-metrics", + "retrieve-a-managed-session-s-resource-cleanup-state", + "release-a-managed-session-s-execution-resources-while-retaining-history", + "list-runtime-observations-across-managed-projects", + "summarize-resource-counts-and-session-usage-by-project-agent-or-creator-key" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/core-administration/query-committed-administrator-mutations.mdx b/apps/docs/content/docs/api-reference/core/core-administration/query-committed-administrator-mutations.mdx new file mode 100644 index 000000000..b5fe25feb --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/query-committed-administrator-mutations.mdx @@ -0,0 +1,22 @@ +--- +title: Query committed administrator mutations +description: Core key only. Newest-first cursor pagination of safe metadata. +full: true +_openapi: + method: GET + route: /core/v1/audit-log + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Actor labels are unverified console labels, not authorization identities. Request bodies and secrets are never recorded. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration/release-a-managed-session-s-execution-resources-while-retaining-history.mdx b/apps/docs/content/docs/api-reference/core/core-administration/release-a-managed-session-s-execution-resources-while-retaining-history.mdx new file mode 100644 index 000000000..39ec2c3c4 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/release-a-managed-session-s-execution-resources-while-retaining-history.mdx @@ -0,0 +1,26 @@ +--- +title: Release a managed Session's execution resources while retaining history +description: Core key only. Requires the current deployment generation; no maintenance mode is required. +full: true +_openapi: + method: POST + route: /core/v1/projects/{project_id}/sessions/{session_id}/archive + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration/retrieve-a-managed-session-s-resource-cleanup-state.mdx b/apps/docs/content/docs/api-reference/core/core-administration/retrieve-a-managed-session-s-resource-cleanup-state.mdx new file mode 100644 index 000000000..ebbc1b0f3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/retrieve-a-managed-session-s-resource-cleanup-state.mdx @@ -0,0 +1,22 @@ +--- +title: Retrieve a managed Session's resource cleanup state +description: Core key only. Reports actual resource disposition, including expiry and failure cleanup. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/archive + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration/retrieve-core-operational-metrics.mdx b/apps/docs/content/docs/api-reference/core/core-administration/retrieve-core-operational-metrics.mdx new file mode 100644 index 000000000..97df1304a --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/retrieve-core-operational-metrics.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve Core operational metrics +description: Core key only. Complete UTC buckets; unknown measurements are null. +full: true +_openapi: + method: GET + route: /core/v1/metrics + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Core key only. Complete UTC buckets; unknown measurements are null. Samples are + process-local and are not backfilled after a restart. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Samples are process-local and are not backfilled after a restart. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration/retrieve-installation-facts-and-process-settings.mdx b/apps/docs/content/docs/api-reference/core/core-administration/retrieve-installation-facts-and-process-settings.mdx new file mode 100644 index 000000000..875f61961 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/retrieve-installation-facts-and-process-settings.mdx @@ -0,0 +1,24 @@ +--- +title: Retrieve installation facts and process settings +description: Core key only; available before any sandbox deployment exists. +full: true +_openapi: + method: GET + route: /core/v1/installation + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/core-administration/summarize-resource-counts-and-session-usage-by-project-agent-or-creator-key.mdx b/apps/docs/content/docs/api-reference/core/core-administration/summarize-resource-counts-and-session-usage-by-project-agent-or-creator-key.mdx new file mode 100644 index 000000000..15cd4992d --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/core-administration/summarize-resource-counts-and-session-usage-by-project-agent-or-creator-key.mdx @@ -0,0 +1,25 @@ +--- +title: Summarize resource counts and Session usage by Project, Agent or creator key +description: Core key only. after/limit/order paginate Projects. +full: true +_openapi: + method: GET + route: /core/v1/summary + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +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. + + \ 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/credentials/delete-a-vault-credential-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/credentials/delete-a-vault-credential-in-a-project.mdx new file mode 100644 index 000000000..26377ff7f --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/credentials/delete-a-vault-credential-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a Vault Credential in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/vaults/{vault_id}/credentials/{credential_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/credentials/index.mdx b/apps/docs/content/docs/api-reference/core/credentials/index.mdx new file mode 100644 index 000000000..ff7903022 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/credentials/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List safe Vault Credential metadata in a Project](/api-reference/core/credentials/list-safe-vault-credential-metadata-in-a-project) | `GET` | `/core/v1/projects/{project_id}/vaults/{vault_id}/credentials` | +| [Retrieve safe Vault Credential metadata in a Project](/api-reference/core/credentials/retrieve-safe-vault-credential-metadata-in-a-project) | `GET` | `/core/v1/projects/{project_id}/vaults/{vault_id}/credentials/{credential_id}` | +| [Delete a Vault Credential in a Project](/api-reference/core/credentials/delete-a-vault-credential-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/vaults/{vault_id}/credentials/{credential_id}` | diff --git a/apps/docs/content/docs/api-reference/core/credentials/list-safe-vault-credential-metadata-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/credentials/list-safe-vault-credential-metadata-in-a-project.mdx new file mode 100644 index 000000000..f9649ed64 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/credentials/list-safe-vault-credential-metadata-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List safe Vault Credential metadata in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/vaults/{vault_id}/credentials + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/credentials/meta.json b/apps/docs/content/docs/api-reference/core/credentials/meta.json new file mode 100644 index 000000000..5fe537ae7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/credentials/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Credentials", + "pages": [ + "list-safe-vault-credential-metadata-in-a-project", + "retrieve-safe-vault-credential-metadata-in-a-project", + "delete-a-vault-credential-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/credentials/retrieve-safe-vault-credential-metadata-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/credentials/retrieve-safe-vault-credential-metadata-in-a-project.mdx new file mode 100644 index 000000000..9df1a2a4c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/credentials/retrieve-safe-vault-credential-metadata-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve safe Vault Credential metadata in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/vaults/{vault_id}/credentials/{credential_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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/deployment-model-providers/index.mdx b/apps/docs/content/docs/api-reference/core/deployment-model-providers/index.mdx new file mode 100644 index 000000000..71db24cf0 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/deployment-model-providers/index.mdx @@ -0,0 +1,13 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List harnesses and their deployment default model providers](/api-reference/core/deployment-model-providers/list-harnesses-and-their-deployment-default-model-providers) | `GET` | `/core/v1/harnesses` | +| [Retrieve a harness's deployment default model provider](/api-reference/core/deployment-model-providers/retrieve-a-harness-s-deployment-default-model-provider) | `GET` | `/core/v1/harnesses/{harness}/model-configuration` | +| [Replace a harness's deployment default model provider](/api-reference/core/deployment-model-providers/replace-a-harness-s-deployment-default-model-provider) | `PUT` | `/core/v1/harnesses/{harness}/model-configuration` | +| [Remove a harness's deployment default model provider](/api-reference/core/deployment-model-providers/remove-a-harness-s-deployment-default-model-provider) | `DELETE` | `/core/v1/harnesses/{harness}/model-configuration` | diff --git a/apps/docs/content/docs/api-reference/core/deployment-model-providers/list-harnesses-and-their-deployment-default-model-providers.mdx b/apps/docs/content/docs/api-reference/core/deployment-model-providers/list-harnesses-and-their-deployment-default-model-providers.mdx new file mode 100644 index 000000000..d0619046b --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/deployment-model-providers/list-harnesses-and-their-deployment-default-model-providers.mdx @@ -0,0 +1,26 @@ +--- +title: List harnesses and their deployment default model providers +description: >- + 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. +full: true +_openapi: + method: GET + route: /core/v1/harnesses + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Keys are never returned; api_key_configured reports that one is set. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/deployment-model-providers/meta.json b/apps/docs/content/docs/api-reference/core/deployment-model-providers/meta.json new file mode 100644 index 000000000..4c66dd121 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/deployment-model-providers/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Deployment Model Providers", + "pages": [ + "list-harnesses-and-their-deployment-default-model-providers", + "retrieve-a-harness-s-deployment-default-model-provider", + "replace-a-harness-s-deployment-default-model-provider", + "remove-a-harness-s-deployment-default-model-provider" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/deployment-model-providers/remove-a-harness-s-deployment-default-model-provider.mdx b/apps/docs/content/docs/api-reference/core/deployment-model-providers/remove-a-harness-s-deployment-default-model-provider.mdx new file mode 100644 index 000000000..3d038bf48 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/deployment-model-providers/remove-a-harness-s-deployment-default-model-provider.mdx @@ -0,0 +1,22 @@ +--- +title: Remove a harness's deployment default model provider +description: Core key only. Idempotent; each successful request is audited. +full: true +_openapi: + method: DELETE + route: /core/v1/harnesses/{harness}/model-configuration + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Sessions that already froze the default keep it. Afterwards new openai_hosted Sessions for this harness need a Session or Agent bundle. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/deployment-model-providers/replace-a-harness-s-deployment-default-model-provider.mdx b/apps/docs/content/docs/api-reference/core/deployment-model-providers/replace-a-harness-s-deployment-default-model-provider.mdx new file mode 100644 index 000000000..cfbfe50f2 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/deployment-model-providers/replace-a-harness-s-deployment-default-model-provider.mdx @@ -0,0 +1,26 @@ +--- +title: Replace a harness's deployment default model provider +description: >- + Core key only. Replaces one complete deployment model configuration, including its write-only + provider key. +full: true +_openapi: + method: PUT + route: /core/v1/harnesses/{harness}/model-configuration + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/deployment-model-providers/retrieve-a-harness-s-deployment-default-model-provider.mdx b/apps/docs/content/docs/api-reference/core/deployment-model-providers/retrieve-a-harness-s-deployment-default-model-provider.mdx new file mode 100644 index 000000000..d9477d1e1 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/deployment-model-providers/retrieve-a-harness-s-deployment-default-model-provider.mdx @@ -0,0 +1,26 @@ +--- +title: Retrieve a harness's deployment default model provider +description: >- + Core key only. Returns the safe view; the key is never returned. 404 when the harness does not + exist or has no deployment default. +full: true +_openapi: + method: GET + route: /core/v1/harnesses/{harness}/model-configuration + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ 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/environment-templates/delete-an-environment-template-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/environment-templates/delete-an-environment-template-in-a-project.mdx new file mode 100644 index 000000000..d7984e045 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/environment-templates/delete-an-environment-template-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete an Environment Template in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/environment-templates/{environment_template_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/environment-templates/index.mdx b/apps/docs/content/docs/api-reference/core/environment-templates/index.mdx new file mode 100644 index 000000000..9c191a9e0 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/environment-templates/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Environment Templates in a Project](/api-reference/core/environment-templates/list-environment-templates-in-a-project) | `GET` | `/core/v1/projects/{project_id}/environment-templates` | +| [Retrieve an Environment Template in a Project](/api-reference/core/environment-templates/retrieve-an-environment-template-in-a-project) | `GET` | `/core/v1/projects/{project_id}/environment-templates/{environment_template_id}` | +| [Delete an Environment Template in a Project](/api-reference/core/environment-templates/delete-an-environment-template-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/environment-templates/{environment_template_id}` | diff --git a/apps/docs/content/docs/api-reference/core/environment-templates/list-environment-templates-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/environment-templates/list-environment-templates-in-a-project.mdx new file mode 100644 index 000000000..763fc5393 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/environment-templates/list-environment-templates-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List Environment Templates in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/environment-templates + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/environment-templates/meta.json b/apps/docs/content/docs/api-reference/core/environment-templates/meta.json new file mode 100644 index 000000000..4543fc6be --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/environment-templates/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Environment Templates", + "pages": [ + "list-environment-templates-in-a-project", + "retrieve-an-environment-template-in-a-project", + "delete-an-environment-template-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/environment-templates/retrieve-an-environment-template-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/environment-templates/retrieve-an-environment-template-in-a-project.mdx new file mode 100644 index 000000000..021e0fc92 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/environment-templates/retrieve-an-environment-template-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve an Environment Template in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/environment-templates/{environment_template_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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/execution-configuration/index.mdx b/apps/docs/content/docs/api-reference/core/execution-configuration/index.mdx new file mode 100644 index 000000000..3c7a41f7c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/execution-configuration/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Retrieve a Session's frozen execution configuration in a Project](/api-reference/core/execution-configuration/retrieve-a-session-s-frozen-execution-configuration-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/execution-configuration` | diff --git a/apps/docs/content/docs/api-reference/core/execution-configuration/meta.json b/apps/docs/content/docs/api-reference/core/execution-configuration/meta.json new file mode 100644 index 000000000..3c004dc05 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/execution-configuration/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Execution configuration", + "pages": [ + "retrieve-a-session-s-frozen-execution-configuration-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/execution-configuration/retrieve-a-session-s-frozen-execution-configuration-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/execution-configuration/retrieve-a-session-s-frozen-execution-configuration-in-a-project.mdx new file mode 100644 index 000000000..22a327d5d --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/execution-configuration/retrieve-a-session-s-frozen-execution-configuration-in-a-project.mdx @@ -0,0 +1,27 @@ +--- +title: Retrieve a Session's frozen execution configuration in a Project +description: Core key only; the Project ID selects the target space and does not authenticate. +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. */} + +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. + + \ 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/executor-credentials/index.mdx b/apps/docs/content/docs/api-reference/core/executor-credentials/index.mdx new file mode 100644 index 000000000..7e5fe80bd --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/executor-credentials/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List a self_hosted Environment's executor credentials](/api-reference/core/executor-credentials/list-a-self-hosted-environment-s-executor-credentials) | `GET` | `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials` | +| [Issue or explicitly rotate a self_hosted Environment executor credential](/api-reference/core/executor-credentials/issue-or-explicitly-rotate-a-self-hosted-environment-executor-credential) | `POST` | `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials` | +| [Revoke a self_hosted Environment executor credential](/api-reference/core/executor-credentials/revoke-a-self-hosted-environment-executor-credential) | `DELETE` | `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials/{key_id}` | diff --git a/apps/docs/content/docs/api-reference/core/executor-credentials/issue-or-explicitly-rotate-a-self-hosted-environment-executor-credential.mdx b/apps/docs/content/docs/api-reference/core/executor-credentials/issue-or-explicitly-rotate-a-self-hosted-environment-executor-credential.mdx new file mode 100644 index 000000000..d9d2c8848 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/executor-credentials/issue-or-explicitly-rotate-a-self-hosted-environment-executor-credential.mdx @@ -0,0 +1,37 @@ +--- +title: Issue or explicitly rotate a self_hosted Environment executor credential +description: >- + 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. +full: true +_openapi: + method: POST + route: /core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/executor-credentials/list-a-self-hosted-environment-s-executor-credentials.mdx b/apps/docs/content/docs/api-reference/core/executor-credentials/list-a-self-hosted-environment-s-executor-credentials.mdx new file mode 100644 index 000000000..7eefad258 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/executor-credentials/list-a-self-hosted-environment-s-executor-credentials.mdx @@ -0,0 +1,26 @@ +--- +title: List a self_hosted Environment's executor credentials +description: >- + Core key only. Returns metadata of the credentials restricted to this Environment, oldest first; + secrets are never listed. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/executor-credentials/meta.json b/apps/docs/content/docs/api-reference/core/executor-credentials/meta.json new file mode 100644 index 000000000..252af8712 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/executor-credentials/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Executor Credentials", + "pages": [ + "list-a-self-hosted-environment-s-executor-credentials", + "issue-or-explicitly-rotate-a-self-hosted-environment-executor-credential", + "revoke-a-self-hosted-environment-executor-credential" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/executor-credentials/revoke-a-self-hosted-environment-executor-credential.mdx b/apps/docs/content/docs/api-reference/core/executor-credentials/revoke-a-self-hosted-environment-executor-credential.mdx new file mode 100644 index 000000000..eaa52e339 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/executor-credentials/revoke-a-self-hosted-environment-executor-credential.mdx @@ -0,0 +1,25 @@ +--- +title: Revoke a self_hosted Environment executor credential +description: >- + Core key only. Revokes one credential restricted to this Environment; repeated revocation is safe + and it also works in an archived Project. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials/{key_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +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. + + \ 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/files/delete-a-source-file-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/files/delete-a-source-file-in-a-project.mdx new file mode 100644 index 000000000..6b67864ca --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/files/delete-a-source-file-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a source file in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/files/{file_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/files/index.mdx b/apps/docs/content/docs/api-reference/core/files/index.mdx new file mode 100644 index 000000000..ca208a7f5 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/files/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List source files in a Project](/api-reference/core/files/list-source-files-in-a-project) | `GET` | `/core/v1/projects/{project_id}/files` | +| [Retrieve source file metadata in a Project](/api-reference/core/files/retrieve-source-file-metadata-in-a-project) | `GET` | `/core/v1/projects/{project_id}/files/{file_id}` | +| [Delete a source file in a Project](/api-reference/core/files/delete-a-source-file-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/files/{file_id}` | diff --git a/apps/docs/content/docs/api-reference/core/files/list-source-files-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/files/list-source-files-in-a-project.mdx new file mode 100644 index 000000000..152e5748f --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/files/list-source-files-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List source files in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/files + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/files/meta.json b/apps/docs/content/docs/api-reference/core/files/meta.json new file mode 100644 index 000000000..9d9b9c8b0 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/files/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Files", + "pages": [ + "list-source-files-in-a-project", + "retrieve-source-file-metadata-in-a-project", + "delete-a-source-file-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/files/retrieve-source-file-metadata-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/files/retrieve-source-file-metadata-in-a-project.mdx new file mode 100644 index 000000000..1fe8e0957 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/files/retrieve-source-file-metadata-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve source file metadata in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/files/{file_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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 index ad2fc6c57..57d0a0c30 100644 --- a/apps/docs/content/docs/api-reference/core/index.mdx +++ b/apps/docs/content/docs/api-reference/core/index.mdx @@ -9,25 +9,25 @@ Generated local management contract. This is not part of the public OpenAI API. 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) +[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) · [Error codes](/error-codes) -- [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) +- [Core Administration](/api-reference/core/core-administration) · 7 operations +- [Deployment Model Providers](/api-reference/core/deployment-model-providers) · 4 operations +- [Administrator Projects](/api-reference/core/administrator-projects) · 7 operations +- [Agents](/api-reference/core/agents) · 3 operations +- [Environment Templates](/api-reference/core/environment-templates) · 3 operations +- [Executor Credentials](/api-reference/core/executor-credentials) · 3 operations +- [Native Installation](/api-reference/core/native-installation) · 1 operation +- [Files](/api-reference/core/files) · 3 operations +- [Write Audit](/api-reference/core/write-audit) · 2 operations +- [Sessions](/api-reference/core/sessions) · 4 operations +- [Artifacts](/api-reference/core/artifacts) · 4 operations +- [Execution configuration](/api-reference/core/execution-configuration) · 1 operation +- [Items](/api-reference/core/items) · 1 operation +- [Runtime history](/api-reference/core/runtime-history) · 1 operation +- [Runtime observations](/api-reference/core/runtime-observations) · 1 operation +- [Turns](/api-reference/core/turns) · 3 operations +- [Skills](/api-reference/core/skills) · 8 operations +- [Vaults](/api-reference/core/vaults) · 3 operations +- [Credentials](/api-reference/core/credentials) · 3 operations +- [Sandbox Manager](/api-reference/core/sandbox-manager) · 13 operations diff --git a/apps/docs/content/docs/api-reference/core/items/index.mdx b/apps/docs/content/docs/api-reference/core/items/index.mdx new file mode 100644 index 000000000..c9a025ddc --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/items/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List persisted execution Items in a Project](/api-reference/core/items/list-persisted-execution-items-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/items` | diff --git a/apps/docs/content/docs/api-reference/core/items.mdx b/apps/docs/content/docs/api-reference/core/items/list-persisted-execution-items-in-a-project.mdx similarity index 60% rename from apps/docs/content/docs/api-reference/core/items.mdx rename to apps/docs/content/docs/api-reference/core/items/list-persisted-execution-items-in-a-project.mdx index 7589bc49b..ffd3957fd 100644 --- a/apps/docs/content/docs/api-reference/core/items.mdx +++ b/apps/docs/content/docs/api-reference/core/items/list-persisted-execution-items-in-a-project.mdx @@ -1,9 +1,6 @@ --- -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. +title: List persisted execution Items in a Project +description: Core key only. full: true _openapi: method: GET @@ -13,11 +10,12 @@ _openapi: 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. + 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 +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/items/meta.json b/apps/docs/content/docs/api-reference/core/items/meta.json new file mode 100644 index 000000000..28b2e109e --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/items/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Items", + "pages": [ + "list-persisted-execution-items-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/meta.json b/apps/docs/content/docs/api-reference/core/meta.json index fb07e650d..c0ea65d04 100644 --- a/apps/docs/content/docs/api-reference/core/meta.json +++ b/apps/docs/content/docs/api-reference/core/meta.json @@ -1,7 +1,6 @@ { "title": "Core administration API", "pages": [ - "index", "core-administration", "deployment-model-providers", "administrator-projects", diff --git a/apps/docs/content/docs/api-reference/core/native-installation.mdx b/apps/docs/content/docs/api-reference/core/native-installation/get-a-self-hosted-session-s-installation-commands.mdx similarity index 54% rename from apps/docs/content/docs/api-reference/core/native-installation.mdx rename to apps/docs/content/docs/api-reference/core/native-installation/get-a-self-hosted-session-s-installation-commands.mdx index a03fdfca8..937d1153a 100644 --- a/apps/docs/content/docs/api-reference/core/native-installation.mdx +++ b/apps/docs/content/docs/api-reference/core/native-installation/get-a-self-hosted-session-s-installation-commands.mdx @@ -1,9 +1,8 @@ --- -title: Native Installation +title: Get a self_hosted Session's installation commands 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. + Core key only. The commands contain a 30-minute installation authorization, never an executor + secret. full: true _openapi: method: GET @@ -13,11 +12,13 @@ _openapi: 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. + 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 +Web displays these same commands provided in public Session creation and detail responses. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/native-installation/index.mdx b/apps/docs/content/docs/api-reference/core/native-installation/index.mdx new file mode 100644 index 000000000..446cd767e --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/native-installation/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Get a self_hosted Session's installation commands](/api-reference/core/native-installation/get-a-self-hosted-session-s-installation-commands) | `GET` | `/core/v1/projects/{project_id}/environments/{environment_id}/installation` | diff --git a/apps/docs/content/docs/api-reference/core/native-installation/meta.json b/apps/docs/content/docs/api-reference/core/native-installation/meta.json new file mode 100644 index 000000000..2b230b174 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/native-installation/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Native Installation", + "pages": [ + "get-a-self-hosted-session-s-installation-commands" + ] +} 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-history/index.mdx b/apps/docs/content/docs/api-reference/core/runtime-history/index.mdx new file mode 100644 index 000000000..7f38d3a59 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/runtime-history/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Retrieve Session Runtime history in a Project](/api-reference/core/runtime-history/retrieve-session-runtime-history-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/runtime-history` | diff --git a/apps/docs/content/docs/api-reference/core/runtime-history/meta.json b/apps/docs/content/docs/api-reference/core/runtime-history/meta.json new file mode 100644 index 000000000..e2be69235 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/runtime-history/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Runtime history", + "pages": [ + "retrieve-session-runtime-history-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/runtime-history/retrieve-session-runtime-history-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/runtime-history/retrieve-session-runtime-history-in-a-project.mdx new file mode 100644 index 000000000..5f1284ddb --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/runtime-history/retrieve-session-runtime-history-in-a-project.mdx @@ -0,0 +1,26 @@ +--- +title: Retrieve Session Runtime history in a Project +description: Core key only; the Project ID selects the target space and does not authenticate. +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. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/runtime-observations/index.mdx b/apps/docs/content/docs/api-reference/core/runtime-observations/index.mdx new file mode 100644 index 000000000..0595320d7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/runtime-observations/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Retrieve a Session Runtime observation in a Project](/api-reference/core/runtime-observations/retrieve-a-session-runtime-observation-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/runtime-observation` | diff --git a/apps/docs/content/docs/api-reference/core/runtime-observations/meta.json b/apps/docs/content/docs/api-reference/core/runtime-observations/meta.json new file mode 100644 index 000000000..583d7ca40 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/runtime-observations/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Runtime observations", + "pages": [ + "retrieve-a-session-runtime-observation-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/runtime-observations.mdx b/apps/docs/content/docs/api-reference/core/runtime-observations/retrieve-a-session-runtime-observation-in-a-project.mdx similarity index 52% rename from apps/docs/content/docs/api-reference/core/runtime-observations.mdx rename to apps/docs/content/docs/api-reference/core/runtime-observations/retrieve-a-session-runtime-observation-in-a-project.mdx index b9a2917ae..8db562e17 100644 --- a/apps/docs/content/docs/api-reference/core/runtime-observations.mdx +++ b/apps/docs/content/docs/api-reference/core/runtime-observations/retrieve-a-session-runtime-observation-in-a-project.mdx @@ -1,9 +1,6 @@ --- -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. +title: Retrieve a Session Runtime observation in a Project +description: Core key only; the Project ID selects the target space and does not authenticate. full: true _openapi: method: GET @@ -13,11 +10,13 @@ _openapi: 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. + 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 +Returns one read-only current Runtime observation. It never provisions, renews, restarts, pauses or stops compute. + + \ 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/sandbox-manager/cancel-a-sandbox-deployment-reset.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/cancel-a-sandbox-deployment-reset.mdx new file mode 100644 index 000000000..0e6bc14ce --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/cancel-a-sandbox-deployment-reset.mdx @@ -0,0 +1,21 @@ +--- +title: Cancel a sandbox deployment reset +description: Restores admission but never restores Sessions already archived. +full: true +_openapi: + method: DELETE + route: /core/v1/sandbox/deployment/reset + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Restores admission but never restores Sessions already archived. With no reset running + this is an idempotent read, provided the generation still matches. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +With no reset running this is an idempotent read, provided the generation still matches. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/change-the-sandbox-deployment-configuration.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/change-the-sandbox-deployment-configuration.mdx new file mode 100644 index 000000000..bc7fc2720 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/change-the-sandbox-deployment-configuration.mdx @@ -0,0 +1,33 @@ +--- +title: Change the sandbox deployment configuration +description: Requires the observed generation, the same backend type and no active reset. +full: true +_openapi: + method: PUT + route: /core/v1/sandbox/deployment + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/create-a-ten-minute-one-use-node-enrollment-token.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/create-a-ten-minute-one-use-node-enrollment-token.mdx new file mode 100644 index 000000000..f0a665d12 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/create-a-ten-minute-one-use-node-enrollment-token.mdx @@ -0,0 +1,21 @@ +--- +title: Create a ten-minute one-use node enrollment token +description: Core key only. Does not grant project resource access. +full: true +_openapi: + method: POST + route: /core/v1/sandbox/enrollment-tokens + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Responses contain only explicit safe fields. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/index.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/index.mdx new file mode 100644 index 000000000..28a2f4f6c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/index.mdx @@ -0,0 +1,22 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Retrieve sandbox deployment](/api-reference/core/sandbox-manager/retrieve-sandbox-deployment) | `GET` | `/core/v1/sandbox/deployment` | +| [Initialize the deployment sandbox provider](/api-reference/core/sandbox-manager/initialize-the-deployment-sandbox-provider) | `POST` | `/core/v1/sandbox/deployment` | +| [Change the sandbox deployment configuration](/api-reference/core/sandbox-manager/change-the-sandbox-deployment-configuration) | `PUT` | `/core/v1/sandbox/deployment` | +| [Start or escalate a durable sandbox deployment reset](/api-reference/core/sandbox-manager/start-or-escalate-a-durable-sandbox-deployment-reset) | `POST` | `/core/v1/sandbox/deployment/reset` | +| [Cancel a sandbox deployment reset](/api-reference/core/sandbox-manager/cancel-a-sandbox-deployment-reset) | `DELETE` | `/core/v1/sandbox/deployment/reset` | +| [List templates visible to an E2B credential](/api-reference/core/sandbox-manager/list-templates-visible-to-an-e2b-credential) | `POST` | `/core/v1/sandbox/e2b/templates` | +| [List ready builds for an E2B template](/api-reference/core/sandbox-manager/list-ready-builds-for-an-e2b-template) | `POST` | `/core/v1/sandbox/e2b/templates/{template_id}/builds` | +| [Create a ten-minute one-use node enrollment token](/api-reference/core/sandbox-manager/create-a-ten-minute-one-use-node-enrollment-token) | `POST` | `/core/v1/sandbox/enrollment-tokens` | +| [List deployment sandbox nodes](/api-reference/core/sandbox-manager/list-deployment-sandbox-nodes) | `GET` | `/core/v1/sandbox/nodes` | +| [Retrieve sandbox node and host history](/api-reference/core/sandbox-manager/retrieve-sandbox-node-and-host-history) | `GET` | `/core/v1/sandbox/nodes/{node_id}` | +| [Update sandbox node name and capacity](/api-reference/core/sandbox-manager/update-sandbox-node-name-and-capacity) | `PATCH` | `/core/v1/sandbox/nodes/{node_id}` | +| [Remove a sandbox node with no retained resources](/api-reference/core/sandbox-manager/remove-a-sandbox-node-with-no-retained-resources) | `DELETE` | `/core/v1/sandbox/nodes/{node_id}` | +| [List retained allocations on a sandbox node](/api-reference/core/sandbox-manager/list-retained-allocations-on-a-sandbox-node) | `GET` | `/core/v1/sandbox/nodes/{node_id}/allocations` | diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/initialize-the-deployment-sandbox-provider.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/initialize-the-deployment-sandbox-provider.mdx new file mode 100644 index 000000000..1c81a814c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/initialize-the-deployment-sandbox-provider.mdx @@ -0,0 +1,37 @@ +--- +title: Initialize the deployment sandbox provider +description: Selects a provider, enforced resource limits and pinned Runtime release. +full: true +_openapi: + method: POST + route: /core/v1/sandbox/deployment + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/list-deployment-sandbox-nodes.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-deployment-sandbox-nodes.mdx new file mode 100644 index 000000000..ac316bdfb --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-deployment-sandbox-nodes.mdx @@ -0,0 +1,21 @@ +--- +title: List deployment sandbox nodes +description: Core key only. Does not grant project resource access. +full: true +_openapi: + method: GET + route: /core/v1/sandbox/nodes + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Responses contain only explicit safe fields. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/list-ready-builds-for-an-e2b-template.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-ready-builds-for-an-e2b-template.mdx new file mode 100644 index 000000000..6662c36c4 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-ready-builds-for-an-e2b-template.mdx @@ -0,0 +1,21 @@ +--- +title: List ready builds for an E2B template +description: Core key only. Reads one template through the pinned SDK helper with a transient E2B credential. +full: true +_openapi: + method: POST + route: /core/v1/sandbox/e2b/templates/{template_id}/builds + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Core key only. Reads one template through the pinned SDK helper with a transient E2B + credential. Returns ready builds only, without allocating compute. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Returns ready builds only, without allocating compute. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/list-retained-allocations-on-a-sandbox-node.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-retained-allocations-on-a-sandbox-node.mdx new file mode 100644 index 000000000..9c24fc3be --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-retained-allocations-on-a-sandbox-node.mdx @@ -0,0 +1,21 @@ +--- +title: List retained allocations on a sandbox node +description: Core key only. Does not grant project resource access. +full: true +_openapi: + method: GET + route: /core/v1/sandbox/nodes/{node_id}/allocations + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Responses contain only explicit safe fields. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/list-templates-visible-to-an-e2b-credential.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-templates-visible-to-an-e2b-credential.mdx new file mode 100644 index 000000000..13a7e8134 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/list-templates-visible-to-an-e2b-credential.mdx @@ -0,0 +1,23 @@ +--- +title: List templates visible to an E2B credential +description: >- + Core key only. Uses a transient E2B credential and endpoint through the pinned SDK helper; returns + safe template metadata. +full: true +_openapi: + method: POST + route: /core/v1/sandbox/e2b/templates + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Does not save the credential or allocate compute. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/meta.json b/apps/docs/content/docs/api-reference/core/sandbox-manager/meta.json new file mode 100644 index 000000000..31404c82e --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/meta.json @@ -0,0 +1,18 @@ +{ + "title": "Sandbox Manager", + "pages": [ + "retrieve-sandbox-deployment", + "initialize-the-deployment-sandbox-provider", + "change-the-sandbox-deployment-configuration", + "start-or-escalate-a-durable-sandbox-deployment-reset", + "cancel-a-sandbox-deployment-reset", + "list-templates-visible-to-an-e2b-credential", + "list-ready-builds-for-an-e2b-template", + "create-a-ten-minute-one-use-node-enrollment-token", + "list-deployment-sandbox-nodes", + "retrieve-sandbox-node-and-host-history", + "update-sandbox-node-name-and-capacity", + "remove-a-sandbox-node-with-no-retained-resources", + "list-retained-allocations-on-a-sandbox-node" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/remove-a-sandbox-node-with-no-retained-resources.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/remove-a-sandbox-node-with-no-retained-resources.mdx new file mode 100644 index 000000000..1a9670037 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/remove-a-sandbox-node-with-no-retained-resources.mdx @@ -0,0 +1,21 @@ +--- +title: Remove a sandbox node with no retained resources +description: Core key only. Does not grant project resource access. +full: true +_openapi: + method: DELETE + route: /core/v1/sandbox/nodes/{node_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Responses contain only explicit safe fields. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-deployment.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-deployment.mdx new file mode 100644 index 000000000..a01e492eb --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-deployment.mdx @@ -0,0 +1,22 @@ +--- +title: Retrieve sandbox deployment +description: Core key only. Does not grant project resource access. +full: true +_openapi: + method: GET + route: /core/v1/sandbox/deployment + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-node-and-host-history.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-node-and-host-history.mdx new file mode 100644 index 000000000..0f7dcdc4e --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-node-and-host-history.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve sandbox node and host history +description: Core key only. Complete UTC buckets. +full: true +_openapi: + method: GET + route: /core/v1/sandbox/nodes/{node_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Core key only. Complete UTC buckets. Missing host measurements and offline history are + null; reads never sample or backfill. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Missing host measurements and offline history are null; reads never sample or backfill. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/start-or-escalate-a-durable-sandbox-deployment-reset.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/start-or-escalate-a-durable-sandbox-deployment-reset.mdx new file mode 100644 index 000000000..684237cf6 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/start-or-escalate-a-durable-sandbox-deployment-reset.mdx @@ -0,0 +1,27 @@ +--- +title: Start or escalate a durable sandbox deployment reset +description: >- + Archives hosted Sessions and waits for confirmed provider cleanup, preserving history and + Files/Artifacts. +full: true +_openapi: + method: POST + route: /core/v1/sandbox/deployment/reset + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sandbox-manager/update-sandbox-node-name-and-capacity.mdx b/apps/docs/content/docs/api-reference/core/sandbox-manager/update-sandbox-node-name-and-capacity.mdx new file mode 100644 index 000000000..750408292 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sandbox-manager/update-sandbox-node-name-and-capacity.mdx @@ -0,0 +1,21 @@ +--- +title: Update sandbox node name and capacity +description: Core key only. Does not grant project resource access. +full: true +_openapi: + method: PATCH + route: /core/v1/sandbox/nodes/{node_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Responses contain only explicit safe fields. + + \ 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/sessions/delete-an-execution-session-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/sessions/delete-an-execution-session-in-a-project.mdx new file mode 100644 index 000000000..ffbe14363 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sessions/delete-an-execution-session-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete an execution Session in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/sessions/{session_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sessions/index.mdx b/apps/docs/content/docs/api-reference/core/sessions/index.mdx new file mode 100644 index 000000000..a4777b09c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sessions/index.mdx @@ -0,0 +1,13 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List execution Sessions in a Project](/api-reference/core/sessions/list-execution-sessions-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions` | +| [Retrieve an execution Session in a Project](/api-reference/core/sessions/retrieve-an-execution-session-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}` | +| [Delete an execution Session in a Project](/api-reference/core/sessions/delete-an-execution-session-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/sessions/{session_id}` | +| [Retrieve root Session diagnostics](/api-reference/core/sessions/retrieve-root-session-diagnostics) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/diagnostics` | diff --git a/apps/docs/content/docs/api-reference/core/sessions/list-execution-sessions-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/sessions/list-execution-sessions-in-a-project.mdx new file mode 100644 index 000000000..13fa099f0 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sessions/list-execution-sessions-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List execution Sessions in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sessions/meta.json b/apps/docs/content/docs/api-reference/core/sessions/meta.json new file mode 100644 index 000000000..964f00992 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sessions/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Sessions", + "pages": [ + "list-execution-sessions-in-a-project", + "retrieve-an-execution-session-in-a-project", + "delete-an-execution-session-in-a-project", + "retrieve-root-session-diagnostics" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/sessions/retrieve-an-execution-session-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/sessions/retrieve-an-execution-session-in-a-project.mdx new file mode 100644 index 000000000..7c5423196 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sessions/retrieve-an-execution-session-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve an execution Session in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/sessions/retrieve-root-session-diagnostics.mdx b/apps/docs/content/docs/api-reference/core/sessions/retrieve-root-session-diagnostics.mdx new file mode 100644 index 000000000..1a2675b23 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/sessions/retrieve-root-session-diagnostics.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve root Session diagnostics +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/diagnostics + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Safe failure categories from one committed snapshot; no native text or historical inference. + + \ 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/skills/delete-a-skill-and-its-versions-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/delete-a-skill-and-its-versions-in-a-project.mdx new file mode 100644 index 000000000..b6bc2f0c1 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/delete-a-skill-and-its-versions-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a Skill and its versions in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/skills/{skill_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/delete-a-skill-version-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/delete-a-skill-version-in-a-project.mdx new file mode 100644 index 000000000..4c2c336a3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/delete-a-skill-version-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a Skill version in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/skills/{skill_id}/versions/{version} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/download-immutable-skill-version-content-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/download-immutable-skill-version-content-in-a-project.mdx new file mode 100644 index 000000000..4ead64999 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/download-immutable-skill-version-content-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Download immutable Skill version content in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/skills/{skill_id}/versions/{version}/content + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/download-skill-content-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/download-skill-content-in-a-project.mdx new file mode 100644 index 000000000..c131a9691 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/download-skill-content-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Download Skill content in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/skills/{skill_id}/content + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/index.mdx b/apps/docs/content/docs/api-reference/core/skills/index.mdx new file mode 100644 index 000000000..a5af14962 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/index.mdx @@ -0,0 +1,17 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Skills in a Project](/api-reference/core/skills/list-skills-in-a-project) | `GET` | `/core/v1/projects/{project_id}/skills` | +| [Retrieve Skill metadata in a Project](/api-reference/core/skills/retrieve-skill-metadata-in-a-project) | `GET` | `/core/v1/projects/{project_id}/skills/{skill_id}` | +| [Delete a Skill and its versions in a Project](/api-reference/core/skills/delete-a-skill-and-its-versions-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/skills/{skill_id}` | +| [Download Skill content in a Project](/api-reference/core/skills/download-skill-content-in-a-project) | `GET` | `/core/v1/projects/{project_id}/skills/{skill_id}/content` | +| [List Skill versions in a Project](/api-reference/core/skills/list-skill-versions-in-a-project) | `GET` | `/core/v1/projects/{project_id}/skills/{skill_id}/versions` | +| [Retrieve Skill version metadata in a Project](/api-reference/core/skills/retrieve-skill-version-metadata-in-a-project) | `GET` | `/core/v1/projects/{project_id}/skills/{skill_id}/versions/{version}` | +| [Delete a Skill version in a Project](/api-reference/core/skills/delete-a-skill-version-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/skills/{skill_id}/versions/{version}` | +| [Download immutable Skill version content in a Project](/api-reference/core/skills/download-immutable-skill-version-content-in-a-project) | `GET` | `/core/v1/projects/{project_id}/skills/{skill_id}/versions/{version}/content` | diff --git a/apps/docs/content/docs/api-reference/core/skills/list-skill-versions-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/list-skill-versions-in-a-project.mdx new file mode 100644 index 000000000..7bbef52f8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/list-skill-versions-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List Skill versions in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/skills/{skill_id}/versions + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/list-skills-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/list-skills-in-a-project.mdx new file mode 100644 index 000000000..de7b2fdbc --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/list-skills-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List Skills in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/skills + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/meta.json b/apps/docs/content/docs/api-reference/core/skills/meta.json new file mode 100644 index 000000000..f7a65be69 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/meta.json @@ -0,0 +1,13 @@ +{ + "title": "Skills", + "pages": [ + "list-skills-in-a-project", + "retrieve-skill-metadata-in-a-project", + "delete-a-skill-and-its-versions-in-a-project", + "download-skill-content-in-a-project", + "list-skill-versions-in-a-project", + "retrieve-skill-version-metadata-in-a-project", + "delete-a-skill-version-in-a-project", + "download-immutable-skill-version-content-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/skills/retrieve-skill-metadata-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/retrieve-skill-metadata-in-a-project.mdx new file mode 100644 index 000000000..70b3fd6a3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/retrieve-skill-metadata-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve Skill metadata in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/skills/{skill_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/skills/retrieve-skill-version-metadata-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/skills/retrieve-skill-version-metadata-in-a-project.mdx new file mode 100644 index 000000000..f061089aa --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/skills/retrieve-skill-version-metadata-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve Skill version metadata in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/skills/{skill_id}/versions/{version} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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/turns/index.mdx b/apps/docs/content/docs/api-reference/core/turns/index.mdx new file mode 100644 index 000000000..23b1d8f4c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/turns/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List execution Turns in a Project](/api-reference/core/turns/list-execution-turns-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/turns` | +| [Retrieve an execution Turn in a Project](/api-reference/core/turns/retrieve-an-execution-turn-in-a-project) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/turns/{turn_id}` | +| [Retrieve root Turn diagnostics](/api-reference/core/turns/retrieve-root-turn-diagnostics) | `GET` | `/core/v1/projects/{project_id}/sessions/{session_id}/turns/{turn_id}/diagnostics` | diff --git a/apps/docs/content/docs/api-reference/core/turns/list-execution-turns-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/turns/list-execution-turns-in-a-project.mdx new file mode 100644 index 000000000..456456a4c --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/turns/list-execution-turns-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List execution Turns in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/turns + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/turns/meta.json b/apps/docs/content/docs/api-reference/core/turns/meta.json new file mode 100644 index 000000000..30e2291cb --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/turns/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Turns", + "pages": [ + "list-execution-turns-in-a-project", + "retrieve-an-execution-turn-in-a-project", + "retrieve-root-turn-diagnostics" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/turns/retrieve-an-execution-turn-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/turns/retrieve-an-execution-turn-in-a-project.mdx new file mode 100644 index 000000000..890c57760 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/turns/retrieve-an-execution-turn-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve an execution Turn in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/turns/{turn_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/turns/retrieve-root-turn-diagnostics.mdx b/apps/docs/content/docs/api-reference/core/turns/retrieve-root-turn-diagnostics.mdx new file mode 100644 index 000000000..7870c4f03 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/turns/retrieve-root-turn-diagnostics.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve root Turn diagnostics +description: Core key only. At most 1000 root Item receipt timings in public Item order. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/sessions/{session_id}/turns/{turn_id}/diagnostics + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Receipt intervals are not native execution durations. + + \ 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/vaults/delete-a-vault-and-all-its-credentials-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/vaults/delete-a-vault-and-all-its-credentials-in-a-project.mdx new file mode 100644 index 000000000..47764157a --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/vaults/delete-a-vault-and-all-its-credentials-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a Vault and all its Credentials in a Project +description: Core key only. +full: true +_openapi: + method: DELETE + route: /core/v1/projects/{project_id}/vaults/{vault_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/vaults/index.mdx b/apps/docs/content/docs/api-reference/core/vaults/index.mdx new file mode 100644 index 000000000..99fd072e8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/vaults/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Vaults in a Project](/api-reference/core/vaults/list-vaults-in-a-project) | `GET` | `/core/v1/projects/{project_id}/vaults` | +| [Retrieve a Vault in a Project](/api-reference/core/vaults/retrieve-a-vault-in-a-project) | `GET` | `/core/v1/projects/{project_id}/vaults/{vault_id}` | +| [Delete a Vault and all its Credentials in a Project](/api-reference/core/vaults/delete-a-vault-and-all-its-credentials-in-a-project) | `DELETE` | `/core/v1/projects/{project_id}/vaults/{vault_id}` | diff --git a/apps/docs/content/docs/api-reference/core/vaults/list-vaults-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/vaults/list-vaults-in-a-project.mdx new file mode 100644 index 000000000..b55b804b3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/vaults/list-vaults-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: List Vaults in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/vaults + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/vaults/meta.json b/apps/docs/content/docs/api-reference/core/vaults/meta.json new file mode 100644 index 000000000..68aaa7e7f --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/vaults/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Vaults", + "pages": [ + "list-vaults-in-a-project", + "retrieve-a-vault-in-a-project", + "delete-a-vault-and-all-its-credentials-in-a-project" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/vaults/retrieve-a-vault-in-a-project.mdx b/apps/docs/content/docs/api-reference/core/vaults/retrieve-a-vault-in-a-project.mdx new file mode 100644 index 000000000..c9899f053 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/vaults/retrieve-a-vault-in-a-project.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve a Vault in a Project +description: Core key only. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/vaults/{vault_id} + 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. */} + +Reuses the public resource projection and operation rules; the Project ID selects the target space and does not authenticate. + + \ 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/core/write-audit/batch-lookup-resource-creation-keys.mdx b/apps/docs/content/docs/api-reference/core/write-audit/batch-lookup-resource-creation-keys.mdx new file mode 100644 index 000000000..845db170e --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/write-audit/batch-lookup-resource-creation-keys.mdx @@ -0,0 +1,22 @@ +--- +title: Batch lookup resource creation keys +description: Core key only. The Project ID path selects its space. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/resource-owners + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Returns null for resources without recorded creation provenance, including historical and foreign resources. No key secret is returned. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/core/write-audit/index.mdx b/apps/docs/content/docs/api-reference/core/write-audit/index.mdx new file mode 100644 index 000000000..282e7909a --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/write-audit/index.mdx @@ -0,0 +1,11 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Batch lookup resource creation keys](/api-reference/core/write-audit/batch-lookup-resource-creation-keys) | `GET` | `/core/v1/projects/{project_id}/resource-owners` | +| [Query API-key write operations](/api-reference/core/write-audit/query-api-key-write-operations) | `GET` | `/core/v1/projects/{project_id}/write-operations` | diff --git a/apps/docs/content/docs/api-reference/core/write-audit/meta.json b/apps/docs/content/docs/api-reference/core/write-audit/meta.json new file mode 100644 index 000000000..464f496e5 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/write-audit/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Write Audit", + "pages": [ + "batch-lookup-resource-creation-keys", + "query-api-key-write-operations" + ] +} diff --git a/apps/docs/content/docs/api-reference/core/write-audit/query-api-key-write-operations.mdx b/apps/docs/content/docs/api-reference/core/write-audit/query-api-key-write-operations.mdx new file mode 100644 index 000000000..ef7d360d8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/core/write-audit/query-api-key-write-operations.mdx @@ -0,0 +1,22 @@ +--- +title: Query API-key write operations +description: Core key only. Reverse chronological keyset pagination over committed writes. +full: true +_openapi: + method: GET + route: /core/v1/projects/{project_id}/write-operations + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Creation records remain; other records follow configured retention. The key path selects its independent space, never a caller-supplied tenant. + + \ 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/credentials/create-a-vault-credential.mdx b/apps/docs/content/docs/api-reference/credentials/create-a-vault-credential.mdx new file mode 100644 index 000000000..3a8091784 --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/create-a-vault-credential.mdx @@ -0,0 +1,40 @@ +--- +title: Create a Vault Credential +description: >- + Stores static_bearer or mcp_oauth secrets as execution-owned authenticated ciphertext without + contacting any endpoint. +full: true +_openapi: + method: POST + route: /vaults/{vault_id}/credentials + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/credentials/delete-a-vault-credential.mdx b/apps/docs/content/docs/api-reference/credentials/delete-a-vault-credential.mdx new file mode 100644 index 000000000..0961872e0 --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/delete-a-vault-credential.mdx @@ -0,0 +1,36 @@ +--- +title: Delete a Vault Credential +description: >- + Removes one Credential and its encrypted token within the authenticated project and owning Vault, + without an encryption key or secret decryption. +full: true +_openapi: + method: DELETE + route: /vaults/{vault_id}/credentials/{credential_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/credentials/index.mdx b/apps/docs/content/docs/api-reference/credentials/index.mdx new file mode 100644 index 000000000..e566b001f --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/index.mdx @@ -0,0 +1,14 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List safe Vault Credential metadata](/api-reference/credentials/list-safe-vault-credential-metadata) | `GET` | `/v1/vaults/{vault_id}/credentials` | +| [Create a Vault Credential](/api-reference/credentials/create-a-vault-credential) | `POST` | `/v1/vaults/{vault_id}/credentials` | +| [Retrieve safe Vault Credential metadata](/api-reference/credentials/retrieve-safe-vault-credential-metadata) | `GET` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | +| [Replace Vault Credential authentication secrets](/api-reference/credentials/replace-vault-credential-authentication-secrets) | `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | +| [Delete a Vault Credential](/api-reference/credentials/delete-a-vault-credential) | `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | diff --git a/apps/docs/content/docs/api-reference/credentials/list-safe-vault-credential-metadata.mdx b/apps/docs/content/docs/api-reference/credentials/list-safe-vault-credential-metadata.mdx new file mode 100644 index 000000000..5460890eb --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/list-safe-vault-credential-metadata.mdx @@ -0,0 +1,35 @@ +--- +title: List safe Vault Credential metadata +description: >- + Lists only metadata from the authenticated project's requested Vault, without decryption or + execution. +full: true +_openapi: + method: GET + route: /vaults/{vault_id}/credentials + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/credentials/meta.json b/apps/docs/content/docs/api-reference/credentials/meta.json new file mode 100644 index 000000000..7382aa9c8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Credentials", + "pages": [ + "list-safe-vault-credential-metadata", + "create-a-vault-credential", + "retrieve-safe-vault-credential-metadata", + "replace-vault-credential-authentication-secrets", + "delete-a-vault-credential" + ] +} diff --git a/apps/docs/content/docs/api-reference/credentials/replace-vault-credential-authentication-secrets.mdx b/apps/docs/content/docs/api-reference/credentials/replace-vault-credential-authentication-secrets.mdx new file mode 100644 index 000000000..1f0b890e9 --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/replace-vault-credential-authentication-secrets.mdx @@ -0,0 +1,42 @@ +--- +title: Replace Vault Credential authentication secrets +description: >- + Explicitly empty static bearer or OAuth access tokens and OAuth patches without a mutable field + are rejected before storage. +full: true +_openapi: + method: POST + route: /vaults/{vault_id}/credentials/{credential_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/credentials/retrieve-safe-vault-credential-metadata.mdx b/apps/docs/content/docs/api-reference/credentials/retrieve-safe-vault-credential-metadata.mdx new file mode 100644 index 000000000..0fa65d1cc --- /dev/null +++ b/apps/docs/content/docs/api-reference/credentials/retrieve-safe-vault-credential-metadata.mdx @@ -0,0 +1,23 @@ +--- +title: Retrieve safe Vault Credential metadata +description: Reads only non-secret metadata scoped to the authenticated project and owning Vault. +full: true +_openapi: + method: GET + route: /vaults/{vault_id}/credentials/{credential_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ 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/environment-templates/create-an-environment-template.mdx b/apps/docs/content/docs/api-reference/environment-templates/create-an-environment-template.mdx new file mode 100644 index 000000000..6f6d1f4ef --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/create-an-environment-template.mdx @@ -0,0 +1,38 @@ +--- +title: Create an Environment Template +description: Saves tenant-owned hosted configuration. +full: true +_openapi: + method: POST + route: /agents/environments/templates + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environment-templates/delete-an-environment-template.mdx b/apps/docs/content/docs/api-reference/environment-templates/delete-an-environment-template.mdx new file mode 100644 index 000000000..1896ba1f3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/delete-an-environment-template.mdx @@ -0,0 +1,21 @@ +--- +title: Delete an Environment Template +description: >- + Deletes the tenant-owned reusable configuration without changing or deleting existing Sessions and + their frozen configuration. +full: true +_openapi: + method: DELETE + route: /agents/environments/templates/{environment_template_id} + toc: [] + structuredData: + headings: [] + contents: + - 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/environment-templates/index.mdx b/apps/docs/content/docs/api-reference/environment-templates/index.mdx new file mode 100644 index 000000000..e2b3a7bda --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/index.mdx @@ -0,0 +1,14 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Environment Templates](/api-reference/environment-templates/list-environment-templates) | `GET` | `/v1/agents/environments/templates` | +| [Create an Environment Template](/api-reference/environment-templates/create-an-environment-template) | `POST` | `/v1/agents/environments/templates` | +| [Retrieve an Environment Template](/api-reference/environment-templates/retrieve-an-environment-template) | `GET` | `/v1/agents/environments/templates/{environment_template_id}` | +| [Update an Environment Template](/api-reference/environment-templates/update-an-environment-template) | `POST` | `/v1/agents/environments/templates/{environment_template_id}` | +| [Delete an Environment Template](/api-reference/environment-templates/delete-an-environment-template) | `DELETE` | `/v1/agents/environments/templates/{environment_template_id}` | diff --git a/apps/docs/content/docs/api-reference/environment-templates/list-environment-templates.mdx b/apps/docs/content/docs/api-reference/environment-templates/list-environment-templates.mdx new file mode 100644 index 000000000..f9c0e044d --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/list-environment-templates.mdx @@ -0,0 +1,23 @@ +--- +title: List Environment Templates +description: Lists tenant-owned safe template metadata in creation order with ID tie-breaking. +full: true +_openapi: + method: GET + route: /agents/environments/templates + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environment-templates/meta.json b/apps/docs/content/docs/api-reference/environment-templates/meta.json new file mode 100644 index 000000000..309876151 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Environment Templates", + "pages": [ + "list-environment-templates", + "create-an-environment-template", + "retrieve-an-environment-template", + "update-an-environment-template", + "delete-an-environment-template" + ] +} diff --git a/apps/docs/content/docs/api-reference/environment-templates/retrieve-an-environment-template.mdx b/apps/docs/content/docs/api-reference/environment-templates/retrieve-an-environment-template.mdx new file mode 100644 index 000000000..372011640 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/retrieve-an-environment-template.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve an Environment Template +description: Returns safe tenant-owned configuration metadata without allocating compute. +full: true +_openapi: + method: GET + route: /agents/environments/templates/{environment_template_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Returns safe tenant-owned configuration metadata without allocating compute. Missing and + foreign resources return the same not-found response. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Missing and foreign resources return the same not-found response. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environment-templates/update-an-environment-template.mdx b/apps/docs/content/docs/api-reference/environment-templates/update-an-environment-template.mdx new file mode 100644 index 000000000..1bae574e9 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environment-templates/update-an-environment-template.mdx @@ -0,0 +1,40 @@ +--- +title: Update an Environment Template +description: Supplied fields replace atomically; omitted fields remain unchanged. +full: true +_openapi: + method: POST + route: /agents/environments/templates/{environment_template_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ 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/environments/create-an-environment-file-from-inline-bytes-or-a-source-file.mdx b/apps/docs/content/docs/api-reference/environments/create-an-environment-file-from-inline-bytes-or-a-source-file.mdx new file mode 100644 index 000000000..182b8a5a6 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environments/create-an-environment-file-from-inline-bytes-or-a-source-file.mdx @@ -0,0 +1,41 @@ +--- +title: Create an Environment file from inline bytes or a source file +description: >- + Uploads standard Base64 bytes to a file beneath /workspace in a qualified local Environment and + returns 201. +full: true +_openapi: + method: POST + route: /agents/environments/{environment_id}/files + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environments/index.mdx b/apps/docs/content/docs/api-reference/environments/index.mdx new file mode 100644 index 000000000..8b005af77 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environments/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Retrieve an execution Environment](/api-reference/environments/retrieve-an-execution-environment) | `GET` | `/v1/agents/environments/{environment_id}` | +| [List live Environment files](/api-reference/environments/list-live-environment-files) | `GET` | `/v1/agents/environments/{environment_id}/files` | +| [Create an Environment file from inline bytes or a source file](/api-reference/environments/create-an-environment-file-from-inline-bytes-or-a-source-file) | `POST` | `/v1/agents/environments/{environment_id}/files` | diff --git a/apps/docs/content/docs/api-reference/environments/list-live-environment-files.mdx b/apps/docs/content/docs/api-reference/environments/list-live-environment-files.mdx new file mode 100644 index 000000000..682126d76 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environments/list-live-environment-files.mdx @@ -0,0 +1,47 @@ +--- +title: List live Environment files +description: Lists direct regular files in one authorized self_hosted or qualified local workspace directory. +full: true +_openapi: + method: GET + route: /agents/environments/{environment_id}/files + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/environments/meta.json b/apps/docs/content/docs/api-reference/environments/meta.json new file mode 100644 index 000000000..2531e78c7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/environments/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Environments", + "pages": [ + "retrieve-an-execution-environment", + "list-live-environment-files", + "create-an-environment-file-from-inline-bytes-or-a-source-file" + ] +} diff --git a/apps/docs/content/docs/api-reference/environments/retrieve-an-execution-environment.mdx b/apps/docs/content/docs/api-reference/environments/retrieve-an-execution-environment.mdx new file mode 100644 index 000000000..246ee75fe --- /dev/null +++ b/apps/docs/content/docs/api-reference/environments/retrieve-an-execution-environment.mdx @@ -0,0 +1,36 @@ +--- +title: Retrieve an execution Environment +description: >- + Returns durable connection status and safe installed metadata for supported self_hosted and basic + openai_hosted profiles. +full: true +_openapi: + method: GET + route: /agents/environments/{environment_id} + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ 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/events/index.mdx b/apps/docs/content/docs/api-reference/events/index.mdx new file mode 100644 index 000000000..fc50c4f35 --- /dev/null +++ b/apps/docs/content/docs/api-reference/events/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Stream live Session events](/api-reference/events/stream-live-session-events) | `GET` | `/v1/agents/sessions/{session_id}/events` | diff --git a/apps/docs/content/docs/api-reference/events/meta.json b/apps/docs/content/docs/api-reference/events/meta.json new file mode 100644 index 000000000..53672b206 --- /dev/null +++ b/apps/docs/content/docs/api-reference/events/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Events", + "pages": [ + "stream-live-session-events" + ] +} diff --git a/apps/docs/content/docs/api-reference/events/stream-live-session-events.mdx b/apps/docs/content/docs/api-reference/events/stream-live-session-events.mdx new file mode 100644 index 000000000..1af1429d6 --- /dev/null +++ b/apps/docs/content/docs/api-reference/events/stream-live-session-events.mdx @@ -0,0 +1,41 @@ +--- +title: Stream live Session events +description: >- + Live-only events, including command output fragments from capable Codex peers as + agent.output.command_execution_output.delta with stable Item/output indexes. +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. */} + +
+Full description + +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. + +
+ + \ 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/files/delete-a-source-file.mdx b/apps/docs/content/docs/api-reference/files/delete-a-source-file.mdx new file mode 100644 index 000000000..274556372 --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/delete-a-source-file.mdx @@ -0,0 +1,25 @@ +--- +title: Delete a source file +description: Atomically deletes project-owned metadata and stored bytes. +full: true +_openapi: + method: DELETE + route: /files/{file_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/files/download-source-file-bytes.mdx b/apps/docs/content/docs/api-reference/files/download-source-file-bytes.mdx new file mode 100644 index 000000000..8541afdd3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/download-source-file-bytes.mdx @@ -0,0 +1,22 @@ +--- +title: Download source file bytes +description: Resolves project-owned File metadata before enforcing download policy. +full: true +_openapi: + method: GET + route: /files/{file_id}/content + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/files/index.mdx b/apps/docs/content/docs/api-reference/files/index.mdx new file mode 100644 index 000000000..bbe9c4ebc --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/index.mdx @@ -0,0 +1,14 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List source files](/api-reference/files/list-source-files) | `GET` | `/v1/files` | +| [Upload a source file](/api-reference/files/upload-a-source-file) | `POST` | `/v1/files` | +| [Retrieve source file metadata](/api-reference/files/retrieve-source-file-metadata) | `GET` | `/v1/files/{file_id}` | +| [Delete a source file](/api-reference/files/delete-a-source-file) | `DELETE` | `/v1/files/{file_id}` | +| [Download source file bytes](/api-reference/files/download-source-file-bytes) | `GET` | `/v1/files/{file_id}/content` | diff --git a/apps/docs/content/docs/api-reference/files/list-source-files.mdx b/apps/docs/content/docs/api-reference/files/list-source-files.mdx new file mode 100644 index 000000000..5aaba62d6 --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/list-source-files.mdx @@ -0,0 +1,28 @@ +--- +title: List source files +description: Lists project-owned Files without reading their bodies. +full: true +_openapi: + method: GET + route: /files + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/files/meta.json b/apps/docs/content/docs/api-reference/files/meta.json new file mode 100644 index 000000000..5c734bddc --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Files", + "pages": [ + "list-source-files", + "upload-a-source-file", + "retrieve-source-file-metadata", + "delete-a-source-file", + "download-source-file-bytes" + ] +} diff --git a/apps/docs/content/docs/api-reference/files/retrieve-source-file-metadata.mdx b/apps/docs/content/docs/api-reference/files/retrieve-source-file-metadata.mdx new file mode 100644 index 000000000..cfd7e870c --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/retrieve-source-file-metadata.mdx @@ -0,0 +1,22 @@ +--- +title: Retrieve source file metadata +description: Returns immutable project-owned user_data file metadata. +full: true +_openapi: + method: GET + route: /files/{file_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +No Beta header is required. Other purposes, expiration and full hosted status/error semantics remain unimplemented or unverified. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/files/upload-a-source-file.mdx b/apps/docs/content/docs/api-reference/files/upload-a-source-file.mdx new file mode 100644 index 000000000..64e0beed9 --- /dev/null +++ b/apps/docs/content/docs/api-reference/files/upload-a-source-file.mdx @@ -0,0 +1,29 @@ +--- +title: Upload a source file +description: >- + Accepts one multipart file and purpose=user_data in either order, with a private 512 MiB content + limit and 64 KiB envelope allowance. +full: true +_openapi: + method: POST + route: /files + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ 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 index e2bee0bf0..eebd3a1d1 100644 --- a/apps/docs/content/docs/api-reference/index.mdx +++ b/apps/docs/content/docs/api-reference/index.mdx @@ -7,18 +7,18 @@ Public schema constrained by the pinned OpenAI Agents API baseline; documented x **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) +[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) · [Error codes](/error-codes) -- [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) +- [Agents](/api-reference/agents) · 5 operations +- [Environments](/api-reference/environments) · 3 operations +- [Environment Templates](/api-reference/environment-templates) · 5 operations +- [Sessions](/api-reference/sessions) · 6 operations +- [Artifacts](/api-reference/artifacts) · 4 operations +- [Events](/api-reference/events) · 1 operation +- [Items](/api-reference/items) · 1 operation +- [Subagents](/api-reference/subagents) · 6 operations +- [Turns](/api-reference/turns) · 2 operations +- [Files](/api-reference/files) · 5 operations +- [Skills](/api-reference/skills) · 11 operations +- [Vaults](/api-reference/vaults) · 4 operations +- [Credentials](/api-reference/credentials) · 5 operations 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/items/index.mdx b/apps/docs/content/docs/api-reference/items/index.mdx new file mode 100644 index 000000000..24672480c --- /dev/null +++ b/apps/docs/content/docs/api-reference/items/index.mdx @@ -0,0 +1,10 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List persisted execution Items](/api-reference/items/list-persisted-execution-items) | `GET` | `/v1/agents/sessions/{session_id}/items` | diff --git a/apps/docs/content/docs/api-reference/items/list-persisted-execution-items.mdx b/apps/docs/content/docs/api-reference/items/list-persisted-execution-items.mdx new file mode 100644 index 000000000..9a910dca8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/items/list-persisted-execution-items.mdx @@ -0,0 +1,23 @@ +--- +title: List persisted execution Items +description: Returns supported message and tool Items in first-observation order. +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. */} + +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`". + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/items/meta.json b/apps/docs/content/docs/api-reference/items/meta.json new file mode 100644 index 000000000..68e4f83d8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/items/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Items", + "pages": [ + "list-persisted-execution-items" + ] +} diff --git a/apps/docs/content/docs/api-reference/machine/index.mdx b/apps/docs/content/docs/api-reference/machine/index.mdx index a6d699b4d..465b3939e 100644 --- a/apps/docs/content/docs/api-reference/machine/index.mdx +++ b/apps/docs/content/docs/api-reference/machine/index.mdx @@ -7,9 +7,9 @@ Generated local machine contract. These connections reach Core directly, never t **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). +This schema covers node configuration, enrollment and identity, and native Runtime installation. 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) +[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) · [Error codes](/error-codes) -- [native-installation](/api-reference/machine/native-installation) -- [sandbox-node](/api-reference/machine/sandbox-node) +- [Native Installation](/api-reference/machine/native-installation) · 2 operations +- [Sandbox Node](/api-reference/machine/sandbox-node) · 3 operations diff --git a/apps/docs/content/docs/api-reference/machine/meta.json b/apps/docs/content/docs/api-reference/machine/meta.json index 5d07906a3..a35d86c95 100644 --- a/apps/docs/content/docs/api-reference/machine/meta.json +++ b/apps/docs/content/docs/api-reference/machine/meta.json @@ -1,7 +1,6 @@ { "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/native-installation/claim-an-environment-s-installation-credential.mdx b/apps/docs/content/docs/api-reference/machine/native-installation/claim-an-environment-s-installation-credential.mdx new file mode 100644 index 000000000..7bcbf9f70 --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/native-installation/claim-an-environment-s-installation-credential.mdx @@ -0,0 +1,22 @@ +--- +title: Claim an Environment's installation credential +description: A valid installation Bearer authorization can claim one connect-only key. +full: true +_openapi: + method: POST + route: /api/v1/agent-daemon/installation/claim + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +The client persists its generated secret before submitting it. Retries must present that same secret; a different, rotated or revoked credential is never replaced. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/machine/native-installation/index.mdx b/apps/docs/content/docs/api-reference/machine/native-installation/index.mdx new file mode 100644 index 000000000..e4fbbe1c3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/native-installation/index.mdx @@ -0,0 +1,11 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Resolve a native installation authorization](/api-reference/machine/native-installation/resolve-a-native-installation-authorization) | `POST` | `/api/v1/agent-daemon/installation` | +| [Claim an Environment's installation credential](/api-reference/machine/native-installation/claim-an-environment-s-installation-credential) | `POST` | `/api/v1/agent-daemon/installation/claim` | diff --git a/apps/docs/content/docs/api-reference/machine/native-installation/meta.json b/apps/docs/content/docs/api-reference/machine/native-installation/meta.json new file mode 100644 index 000000000..0cd526bdd --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/native-installation/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Native Installation", + "pages": [ + "resolve-a-native-installation-authorization", + "claim-an-environment-s-installation-credential" + ] +} diff --git a/apps/docs/content/docs/api-reference/machine/native-installation/resolve-a-native-installation-authorization.mdx b/apps/docs/content/docs/api-reference/machine/native-installation/resolve-a-native-installation-authorization.mdx new file mode 100644 index 000000000..77ccab6f3 --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/native-installation/resolve-a-native-installation-authorization.mdx @@ -0,0 +1,21 @@ +--- +title: Resolve a native installation authorization +description: Accepts a short-lived Environment installation Bearer authorization, not a Project or Core key. +full: true +_openapi: + method: POST + route: /api/v1/agent-daemon/installation + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Returns frozen connection constraints; it does not claim or rotate credentials. + + \ 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/machine/sandbox-node/enroll-a-sandbox-node.mdx b/apps/docs/content/docs/api-reference/machine/sandbox-node/enroll-a-sandbox-node.mdx new file mode 100644 index 000000000..eb47fb22f --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/sandbox-node/enroll-a-sandbox-node.mdx @@ -0,0 +1,25 @@ +--- +title: Enroll a sandbox node +description: >- + Node machine connection. Consumes a one-use enrollment token; grants no project or administrator + access. +full: true +_openapi: + method: POST + route: /api/v1/sandbox-node/enroll + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/machine/sandbox-node/index.mdx b/apps/docs/content/docs/api-reference/machine/sandbox-node/index.mdx new file mode 100644 index 000000000..ccde17e60 --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/sandbox-node/index.mdx @@ -0,0 +1,12 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [Read the active configuration for node installation](/api-reference/machine/sandbox-node/read-the-active-configuration-for-node-installation) | `GET` | `/api/v1/sandbox-node/configuration` | +| [Enroll a sandbox node](/api-reference/machine/sandbox-node/enroll-a-sandbox-node) | `POST` | `/api/v1/sandbox-node/enroll` | +| [Recover an enrolled sandbox node identity and observe its readiness](/api-reference/machine/sandbox-node/recover-an-enrolled-sandbox-node-identity-and-observe-its-readiness) | `GET` | `/api/v1/sandbox-node/identity` | diff --git a/apps/docs/content/docs/api-reference/machine/sandbox-node/meta.json b/apps/docs/content/docs/api-reference/machine/sandbox-node/meta.json new file mode 100644 index 000000000..eb0ad0124 --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/sandbox-node/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Sandbox Node", + "pages": [ + "read-the-active-configuration-for-node-installation", + "enroll-a-sandbox-node", + "recover-an-enrolled-sandbox-node-identity-and-observe-its-readiness" + ] +} diff --git a/apps/docs/content/docs/api-reference/machine/sandbox-node/read-the-active-configuration-for-node-installation.mdx b/apps/docs/content/docs/api-reference/machine/sandbox-node/read-the-active-configuration-for-node-installation.mdx new file mode 100644 index 000000000..cdcc2791c --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/sandbox-node/read-the-active-configuration-for-node-installation.mdx @@ -0,0 +1,24 @@ +--- +title: Read the active configuration for node installation +description: >- + Authenticates with an unconsumed enrollment token, or a retained node credential with + X-OAC-Node-ID. +full: true +_openapi: + method: GET + route: /api/v1/sandbox-node/configuration + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Does not consume the token or expose E2B credentials. Node files cannot override this specification. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/machine/sandbox-node/recover-an-enrolled-sandbox-node-identity-and-observe-its-readiness.mdx b/apps/docs/content/docs/api-reference/machine/sandbox-node/recover-an-enrolled-sandbox-node-identity-and-observe-its-readiness.mdx new file mode 100644 index 000000000..5e14b5fe1 --- /dev/null +++ b/apps/docs/content/docs/api-reference/machine/sandbox-node/recover-an-enrolled-sandbox-node-identity-and-observe-its-readiness.mdx @@ -0,0 +1,23 @@ +--- +title: Recover an enrolled sandbox node identity and observe its readiness +description: >- + Node machine connection. Authenticates with the retained node credential; grants no project or + administrator access. +full: true +_openapi: + method: GET + route: /api/v1/sandbox-node/identity + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +Responses contain only explicit safe fields. + + \ 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 index f96a25397..9e23f4fae 100644 --- a/apps/docs/content/docs/api-reference/meta.json +++ b/apps/docs/content/docs/api-reference/meta.json @@ -1,7 +1,6 @@ { "title": "Application API", "pages": [ - "index", "agents", "environments", "environment-templates", 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 011a38b27..000000000 --- a/apps/docs/content/docs/api-reference/sessions.mdx +++ /dev/null @@ -1,246 +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. Other MCP origins and - native OAuth login remain 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 service - origin, optionally authenticated by the attached Vault rules. 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; - HTTP MCP remains unsupported. 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/sessions/create-an-execution-session.mdx b/apps/docs/content/docs/api-reference/sessions/create-an-execution-session.mdx new file mode 100644 index 000000000..4f3bcfddd --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/create-an-execution-session.mdx @@ -0,0 +1,186 @@ +--- +title: Create an execution Session +description: >- + 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. +full: true +_openapi: + method: POST + route: /agents/sessions + toc: [] + structuredData: + headings: [] + contents: + - 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. Other MCP origins and native OAuth login remain 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 service origin, optionally authenticated by + the attached Vault rules. 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; + HTTP MCP remains unsupported. 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. Other MCP origins and native OAuth login remain 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 service origin, optionally authenticated by the attached Vault rules. + +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.<key> 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; HTTP MCP remains unsupported. 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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/sessions/delete-an-execution-session.mdx b/apps/docs/content/docs/api-reference/sessions/delete-an-execution-session.mdx new file mode 100644 index 000000000..8955f330b --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/delete-an-execution-session.mdx @@ -0,0 +1,34 @@ +--- +title: Delete an execution Session +description: Removes a durably idle or failed Session and its history from the public API. +full: true +_openapi: + method: DELETE + route: /agents/sessions/{session_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/sessions/index.mdx b/apps/docs/content/docs/api-reference/sessions/index.mdx new file mode 100644 index 000000000..bbe609d98 --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/index.mdx @@ -0,0 +1,15 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List execution Sessions](/api-reference/sessions/list-execution-sessions) | `GET` | `/v1/agents/sessions` | +| [Create an execution Session](/api-reference/sessions/create-an-execution-session) | `POST` | `/v1/agents/sessions` | +| [Retrieve an execution Session](/api-reference/sessions/retrieve-an-execution-session) | `GET` | `/v1/agents/sessions/{session_id}` | +| [Update execution Session metadata](/api-reference/sessions/update-execution-session-metadata) | `POST` | `/v1/agents/sessions/{session_id}` | +| [Delete an execution Session](/api-reference/sessions/delete-an-execution-session) | `DELETE` | `/v1/agents/sessions/{session_id}` | +| [Submit Session input events](/api-reference/sessions/submit-session-input-events) | `POST` | `/v1/agents/sessions/{session_id}/events` | diff --git a/apps/docs/content/docs/api-reference/sessions/list-execution-sessions.mdx b/apps/docs/content/docs/api-reference/sessions/list-execution-sessions.mdx new file mode 100644 index 000000000..fd644b16c --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/list-execution-sessions.mdx @@ -0,0 +1,26 @@ +--- +title: List execution Sessions +description: >- + Cursor and results are scoped to the authenticated execution tenant; an unknown, malformed or + foreign after cursor returns not found. +full: true +_openapi: + method: GET + route: /agents/sessions + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/sessions/meta.json b/apps/docs/content/docs/api-reference/sessions/meta.json new file mode 100644 index 000000000..0743e2d6b --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Sessions", + "pages": [ + "list-execution-sessions", + "create-an-execution-session", + "retrieve-an-execution-session", + "update-execution-session-metadata", + "delete-an-execution-session", + "submit-session-input-events" + ] +} diff --git a/apps/docs/content/docs/api-reference/sessions/retrieve-an-execution-session.mdx b/apps/docs/content/docs/api-reference/sessions/retrieve-an-execution-session.mdx new file mode 100644 index 000000000..3ea9afdeb --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/retrieve-an-execution-session.mdx @@ -0,0 +1,23 @@ +--- +title: Retrieve an execution Session +description: Returns supported none, self_hosted and basic openai_hosted Session environments. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/sessions/submit-session-input-events.mdx b/apps/docs/content/docs/api-reference/sessions/submit-session-input-events.mdx new file mode 100644 index 000000000..c9d942063 --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/submit-session-input-events.mdx @@ -0,0 +1,76 @@ +--- +title: Submit Session input events +description: >- + An empty events array is a resource-authorized no-op; it creates no execution retry identity, + Turn, Item or input receipt. +full: true +_openapi: + method: POST + route: /agents/sessions/{session_id}/events + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/sessions/update-execution-session-metadata.mdx b/apps/docs/content/docs/api-reference/sessions/update-execution-session-metadata.mdx new file mode 100644 index 000000000..62edefbd8 --- /dev/null +++ b/apps/docs/content/docs/api-reference/sessions/update-execution-session-metadata.mdx @@ -0,0 +1,33 @@ +--- +title: Update execution Session metadata +description: The metadata field is required in an update body. +full: true +_openapi: + method: POST + route: /agents/sessions/{session_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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.<key> 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. + +
+ + \ 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/skills/delete-a-skill-and-its-versions.mdx b/apps/docs/content/docs/api-reference/skills/delete-a-skill-and-its-versions.mdx new file mode 100644 index 000000000..086cb281c --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/delete-a-skill-and-its-versions.mdx @@ -0,0 +1,21 @@ +--- +title: Delete a Skill and its versions +description: Deletes tenant-owned source bundles. +full: true +_openapi: + method: DELETE + route: /skills/{skill_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Deletes tenant-owned source bundles. Existing Session installation snapshots remain + independent. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Existing Session installation snapshots remain independent. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/delete-a-skill-version.mdx b/apps/docs/content/docs/api-reference/skills/delete-a-skill-version.mdx new file mode 100644 index 000000000..ddd03b4be --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/delete-a-skill-version.mdx @@ -0,0 +1,24 @@ +--- +title: Delete a Skill version +description: >- + Deleting the only remaining version also deletes the Skill; existing Session installation + snapshots remain independent. +full: true +_openapi: + method: DELETE + route: /skills/{skill_id}/versions/{version} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +The default version cannot be deleted while other versions remain. Version numbers are never reused. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/download-immutable-skill-version-content.mdx b/apps/docs/content/docs/api-reference/skills/download-immutable-skill-version-content.mdx new file mode 100644 index 000000000..89f01acaa --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/download-immutable-skill-version-content.mdx @@ -0,0 +1,16 @@ +--- +title: Download immutable Skill version content +full: true +_openapi: + method: GET + route: /skills/{skill_id}/versions/{version}/content + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/download-skill-content.mdx b/apps/docs/content/docs/api-reference/skills/download-skill-content.mdx new file mode 100644 index 000000000..40468a62b --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/download-skill-content.mdx @@ -0,0 +1,22 @@ +--- +title: Download Skill content +description: Downloads an authorized ZIP using the default pointer when no concrete version is supplied. +full: true +_openapi: + method: GET + route: /skills/{skill_id}/content + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Exact upstream unversioned selection, content headers and range semantics remain unverified. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/index.mdx b/apps/docs/content/docs/api-reference/skills/index.mdx new file mode 100644 index 000000000..8cf8bd7b1 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/index.mdx @@ -0,0 +1,20 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Skills](/api-reference/skills/list-skills) | `GET` | `/v1/skills` | +| [Upload a Skill](/api-reference/skills/upload-a-skill) | `POST` | `/v1/skills` | +| [Retrieve Skill metadata](/api-reference/skills/retrieve-skill-metadata) | `GET` | `/v1/skills/{skill_id}` | +| [Update the default Skill version](/api-reference/skills/update-the-default-skill-version) | `POST` | `/v1/skills/{skill_id}` | +| [Delete a Skill and its versions](/api-reference/skills/delete-a-skill-and-its-versions) | `DELETE` | `/v1/skills/{skill_id}` | +| [Download Skill content](/api-reference/skills/download-skill-content) | `GET` | `/v1/skills/{skill_id}/content` | +| [List Skill versions](/api-reference/skills/list-skill-versions) | `GET` | `/v1/skills/{skill_id}/versions` | +| [Upload an immutable Skill version](/api-reference/skills/upload-an-immutable-skill-version) | `POST` | `/v1/skills/{skill_id}/versions` | +| [Retrieve Skill version metadata](/api-reference/skills/retrieve-skill-version-metadata) | `GET` | `/v1/skills/{skill_id}/versions/{version}` | +| [Delete a Skill version](/api-reference/skills/delete-a-skill-version) | `DELETE` | `/v1/skills/{skill_id}/versions/{version}` | +| [Download immutable Skill version content](/api-reference/skills/download-immutable-skill-version-content) | `GET` | `/v1/skills/{skill_id}/versions/{version}/content` | diff --git a/apps/docs/content/docs/api-reference/skills/list-skill-versions.mdx b/apps/docs/content/docs/api-reference/skills/list-skill-versions.mdx new file mode 100644 index 000000000..16ba6df07 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/list-skill-versions.mdx @@ -0,0 +1,24 @@ +--- +title: List Skill versions +description: Orders by version number; after identifies a version resource, not a version number. +full: true +_openapi: + method: GET + route: /skills/{skill_id}/versions + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/list-skills.mdx b/apps/docs/content/docs/api-reference/skills/list-skills.mdx new file mode 100644 index 000000000..b53f27b15 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/list-skills.mdx @@ -0,0 +1,22 @@ +--- +title: List Skills +description: Lists tenant-owned metadata in timestamp order. +full: true +_openapi: + method: GET + route: /skills + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/meta.json b/apps/docs/content/docs/api-reference/skills/meta.json new file mode 100644 index 000000000..b231e6804 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/meta.json @@ -0,0 +1,16 @@ +{ + "title": "Skills", + "pages": [ + "list-skills", + "upload-a-skill", + "retrieve-skill-metadata", + "update-the-default-skill-version", + "delete-a-skill-and-its-versions", + "download-skill-content", + "list-skill-versions", + "upload-an-immutable-skill-version", + "retrieve-skill-version-metadata", + "delete-a-skill-version", + "download-immutable-skill-version-content" + ] +} diff --git a/apps/docs/content/docs/api-reference/skills/retrieve-skill-metadata.mdx b/apps/docs/content/docs/api-reference/skills/retrieve-skill-metadata.mdx new file mode 100644 index 000000000..4ddcc70ab --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/retrieve-skill-metadata.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve Skill metadata +description: Returns tenant-owned metadata without decrypting contents or starting Runtime. +full: true +_openapi: + method: GET + route: /skills/{skill_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Returns tenant-owned metadata without decrypting contents or starting Runtime. 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 Beta header is required. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/retrieve-skill-version-metadata.mdx b/apps/docs/content/docs/api-reference/skills/retrieve-skill-version-metadata.mdx new file mode 100644 index 000000000..3dca7d040 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/retrieve-skill-version-metadata.mdx @@ -0,0 +1,16 @@ +--- +title: Retrieve Skill version metadata +full: true +_openapi: + method: GET + route: /skills/{skill_id}/versions/{version} + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/update-the-default-skill-version.mdx b/apps/docs/content/docs/api-reference/skills/update-the-default-skill-version.mdx new file mode 100644 index 000000000..42587594d --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/update-the-default-skill-version.mdx @@ -0,0 +1,21 @@ +--- +title: Update the default Skill version +description: >- + Changes only the tenant-owned default pointer; immutable versions and existing Session snapshots + remain unchanged. +full: true +_openapi: + method: POST + route: /skills/{skill_id} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Changes only the tenant-owned default pointer; immutable versions and existing Session + snapshots remain unchanged. +--- + +{/* 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/upload-a-skill.mdx b/apps/docs/content/docs/api-reference/skills/upload-a-skill.mdx new file mode 100644 index 000000000..f399a3e80 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/upload-a-skill.mdx @@ -0,0 +1,22 @@ +--- +title: Upload a Skill +description: Accepts one ZIP in files or a directory in files[]. +full: true +_openapi: + method: POST + route: /skills + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Applies the qualified portable Skill bundle profile. No Beta header is required; full hosted upload limits and activation extensions are not qualified. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/skills/upload-an-immutable-skill-version.mdx b/apps/docs/content/docs/api-reference/skills/upload-an-immutable-skill-version.mdx new file mode 100644 index 000000000..ebc6eedc4 --- /dev/null +++ b/apps/docs/content/docs/api-reference/skills/upload-an-immutable-skill-version.mdx @@ -0,0 +1,16 @@ +--- +title: Upload an immutable Skill version +full: true +_openapi: + method: POST + route: /skills/{skill_id}/versions + toc: [] + structuredData: + headings: [] + contents: [] +description: '' +--- + +{/* 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/subagents/index.mdx b/apps/docs/content/docs/api-reference/subagents/index.mdx new file mode 100644 index 000000000..a7031da4b --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/index.mdx @@ -0,0 +1,15 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Session Subagents](/api-reference/subagents/list-session-subagents) | `GET` | `/v1/agents/sessions/{session_id}/subagents` | +| [Retrieve a Session Subagent](/api-reference/subagents/retrieve-a-session-subagent) | `GET` | `/v1/agents/sessions/{session_id}/subagents/{subagent_id}` | +| [List a Subagent's Items](/api-reference/subagents/list-a-subagent-s-items) | `GET` | `/v1/agents/sessions/{session_id}/subagents/{subagent_id}/items` | +| [List a Subagent's Turns](/api-reference/subagents/list-a-subagent-s-turns) | `GET` | `/v1/agents/sessions/{session_id}/subagents/{subagent_id}/turns` | +| [Retrieve a Subagent Turn](/api-reference/subagents/retrieve-a-subagent-turn) | `GET` | `/v1/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}` | +| [List a Subagent Turn's Items](/api-reference/subagents/list-a-subagent-turn-s-items) | `GET` | `/v1/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items` | diff --git a/apps/docs/content/docs/api-reference/subagents/list-a-subagent-s-items.mdx b/apps/docs/content/docs/api-reference/subagents/list-a-subagent-s-items.mdx new file mode 100644 index 000000000..ad08099bf --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/list-a-subagent-s-items.mdx @@ -0,0 +1,23 @@ +--- +title: List a Subagent's Items +description: Returns only this Subagent's own Items across all its Turns, not its descendants' Items. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/subagents/{subagent_id}/items + toc: [] + structuredData: + headings: [] + contents: + - 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`". +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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`". + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/subagents/list-a-subagent-s-turns.mdx b/apps/docs/content/docs/api-reference/subagents/list-a-subagent-s-turns.mdx new file mode 100644 index 000000000..c10e870b5 --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/list-a-subagent-s-turns.mdx @@ -0,0 +1,26 @@ +--- +title: List a Subagent's Turns +description: Includes this Subagent's Turns after resume, with the Session's Agent ID as agent_id. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/subagents/{subagent_id}/turns + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/subagents/list-a-subagent-turn-s-items.mdx b/apps/docs/content/docs/api-reference/subagents/list-a-subagent-turn-s-items.mdx new file mode 100644 index 000000000..b3b49bb1a --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/list-a-subagent-turn-s-items.mdx @@ -0,0 +1,22 @@ +--- +title: List a Subagent Turn's Items +description: Returns Items owned by this exact Subagent Turn. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +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`". + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/subagents/list-session-subagents.mdx b/apps/docs/content/docs/api-reference/subagents/list-session-subagents.mdx new file mode 100644 index 000000000..1108529f2 --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/list-session-subagents.mdx @@ -0,0 +1,23 @@ +--- +title: List Session Subagents +description: Includes nested and closed Subagents. Cursors are Subagents of the same tenant and Session. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/subagents + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/subagents/meta.json b/apps/docs/content/docs/api-reference/subagents/meta.json new file mode 100644 index 000000000..adfac2576 --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Subagents", + "pages": [ + "list-session-subagents", + "retrieve-a-session-subagent", + "list-a-subagent-s-items", + "list-a-subagent-s-turns", + "retrieve-a-subagent-turn", + "list-a-subagent-turn-s-items" + ] +} diff --git a/apps/docs/content/docs/api-reference/subagents/retrieve-a-session-subagent.mdx b/apps/docs/content/docs/api-reference/subagents/retrieve-a-session-subagent.mdx new file mode 100644 index 000000000..02789e367 --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/retrieve-a-session-subagent.mdx @@ -0,0 +1,22 @@ +--- +title: Retrieve a Session Subagent +description: Returns this Session's persisted Subagent. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/subagents/{subagent_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Active includes idle between Turns. Resuming preserves opened_at and clears closed_at. Unknown or inaccessible parent scopes return not found. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/subagents/retrieve-a-subagent-turn.mdx b/apps/docs/content/docs/api-reference/subagents/retrieve-a-subagent-turn.mdx new file mode 100644 index 000000000..5b76e16e7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/subagents/retrieve-a-subagent-turn.mdx @@ -0,0 +1,24 @@ +--- +title: Retrieve a Subagent Turn +description: >- + Returns a Turn owned by this Subagent. Its agent_id is the Session's Agent ID and its subagent_id + identifies the Subagent. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Session Turn routes do not return child Turns. Unknown or inaccessible parent scopes return not found. + + \ 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/turns/index.mdx b/apps/docs/content/docs/api-reference/turns/index.mdx new file mode 100644 index 000000000..17e467b86 --- /dev/null +++ b/apps/docs/content/docs/api-reference/turns/index.mdx @@ -0,0 +1,11 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List execution Turns](/api-reference/turns/list-execution-turns) | `GET` | `/v1/agents/sessions/{session_id}/turns` | +| [Retrieve an execution Turn](/api-reference/turns/retrieve-an-execution-turn) | `GET` | `/v1/agents/sessions/{session_id}/turns/{turn_id}` | diff --git a/apps/docs/content/docs/api-reference/turns/list-execution-turns.mdx b/apps/docs/content/docs/api-reference/turns/list-execution-turns.mdx new file mode 100644 index 000000000..bc0dc12cd --- /dev/null +++ b/apps/docs/content/docs/api-reference/turns/list-execution-turns.mdx @@ -0,0 +1,25 @@ +--- +title: List execution Turns +description: >- + Returns the Session's root Turns in creation order; Subagent Turns are listed through the Subagent + Turn routes. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/turns + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +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. + + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/turns/meta.json b/apps/docs/content/docs/api-reference/turns/meta.json new file mode 100644 index 000000000..7a2b5c34f --- /dev/null +++ b/apps/docs/content/docs/api-reference/turns/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Turns", + "pages": [ + "list-execution-turns", + "retrieve-an-execution-turn" + ] +} diff --git a/apps/docs/content/docs/api-reference/turns/retrieve-an-execution-turn.mdx b/apps/docs/content/docs/api-reference/turns/retrieve-an-execution-turn.mdx new file mode 100644 index 000000000..c244c4159 --- /dev/null +++ b/apps/docs/content/docs/api-reference/turns/retrieve-an-execution-turn.mdx @@ -0,0 +1,21 @@ +--- +title: Retrieve an execution Turn +description: Returns a root Turn of this Session. +full: true +_openapi: + method: GET + route: /agents/sessions/{session_id}/turns/{turn_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +A Subagent Turn ID returns the same not found error as a missing Turn; read it through the Subagent Turn routes. + + \ 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/api-reference/vaults/create-a-vault.mdx b/apps/docs/content/docs/api-reference/vaults/create-a-vault.mdx new file mode 100644 index 000000000..7b3ecdf12 --- /dev/null +++ b/apps/docs/content/docs/api-reference/vaults/create-a-vault.mdx @@ -0,0 +1,32 @@ +--- +title: Create a Vault +description: Creates a project-owned Vault independently of execution. +full: true +_openapi: + method: POST + route: /vaults + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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.<key> 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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/vaults/delete-a-vault-and-all-its-credentials.mdx b/apps/docs/content/docs/api-reference/vaults/delete-a-vault-and-all-its-credentials.mdx new file mode 100644 index 000000000..0284ea3d7 --- /dev/null +++ b/apps/docs/content/docs/api-reference/vaults/delete-a-vault-and-all-its-credentials.mdx @@ -0,0 +1,35 @@ +--- +title: Delete a Vault and all its Credentials +description: >- + Atomically removes the authenticated project's Vault and all its stored Credentials without an + encryption key, decryption or external requests. +full: true +_openapi: + method: DELETE + route: /vaults/{vault_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/vaults/index.mdx b/apps/docs/content/docs/api-reference/vaults/index.mdx new file mode 100644 index 000000000..00b22a93a --- /dev/null +++ b/apps/docs/content/docs/api-reference/vaults/index.mdx @@ -0,0 +1,13 @@ +--- +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. + +| Operation | Method | Path | +| --- | --- | --- | +| [List Vaults](/api-reference/vaults/list-vaults) | `GET` | `/v1/vaults` | +| [Create a Vault](/api-reference/vaults/create-a-vault) | `POST` | `/v1/vaults` | +| [Retrieve a Vault](/api-reference/vaults/retrieve-a-vault) | `GET` | `/v1/vaults/{vault_id}` | +| [Delete a Vault and all its Credentials](/api-reference/vaults/delete-a-vault-and-all-its-credentials) | `DELETE` | `/v1/vaults/{vault_id}` | diff --git a/apps/docs/content/docs/api-reference/vaults/list-vaults.mdx b/apps/docs/content/docs/api-reference/vaults/list-vaults.mdx new file mode 100644 index 000000000..e93d6e144 --- /dev/null +++ b/apps/docs/content/docs/api-reference/vaults/list-vaults.mdx @@ -0,0 +1,32 @@ +--- +title: List Vaults +description: Lists project-owned Vaults independently of execution. +full: true +_openapi: + method: GET + route: /vaults + 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +
+Full description + +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. + +
+ + \ No newline at end of file diff --git a/apps/docs/content/docs/api-reference/vaults/meta.json b/apps/docs/content/docs/api-reference/vaults/meta.json new file mode 100644 index 000000000..22f1a6b90 --- /dev/null +++ b/apps/docs/content/docs/api-reference/vaults/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Vaults", + "pages": [ + "list-vaults", + "create-a-vault", + "retrieve-a-vault", + "delete-a-vault-and-all-its-credentials" + ] +} diff --git a/apps/docs/content/docs/api-reference/vaults/retrieve-a-vault.mdx b/apps/docs/content/docs/api-reference/vaults/retrieve-a-vault.mdx new file mode 100644 index 000000000..ee6057796 --- /dev/null +++ b/apps/docs/content/docs/api-reference/vaults/retrieve-a-vault.mdx @@ -0,0 +1,24 @@ +--- +title: Retrieve a Vault +description: >- + Reads a Vault owned by the authenticated project without resolving credentials, Sessions or + execution devices. +full: true +_openapi: + method: GET + route: /vaults/{vault_id} + toc: [] + structuredData: + headings: [] + contents: + - 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. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Missing and foreign IDs share the same not-found response; exact hosted error semantics remain unverified. + + \ No newline at end of file diff --git a/apps/docs/content/docs/architecture.mdx b/apps/docs/content/docs/architecture.mdx new file mode 100644 index 000000000..68647b2c9 --- /dev/null +++ b/apps/docs/content/docs/architecture.mdx @@ -0,0 +1,105 @@ +--- +title: "Architecture" +description: "Core, the Runtime daemon and the native harness: the three namespaces, replaceable parts and a Session end to end." +--- + +OpenAgentCore separates control, runtime and execution. Core owns durable state +and the API; the Runtime daemon runs work inside an Environment; the native harness +keeps its own model and tool loop. Each connection between them is a defined +protocol, so any part can be replaced without changing Core orchestration. + +This page is a map. Each section names a component, its boundary and the document +that owns its rules. + +![OpenAgentCore architecture](/images/source/docs/assets/architecture-overview.png) + +The diagram has four tiers: + +1. **Callers.** Applications, including your product and the official OpenAI SDK, + call the Agents API. Operators use Core Web, which calls the Core API. +2. **Core.** The control plane: public and administrator APIs, resources, + orchestration, PostgreSQL, the Runtime gateway and the Sandbox Provider + interface. +3. **Environment.** Where the agent works: a Core-managed sandbox or your own + machine. The Runtime daemon prepares capabilities and starts the native harness, + which works on the workspace and tools. +4. **Outside Core.** The model API and remote MCP servers, called by the harness + with the Session's model provider. + +## Two APIs, and a machine channel + +![Three namespaces and their credentials](/images/source/docs/assets/architecture-api-surfaces.png) + +Core serves three namespaces: the Agents API (`/v1`) for applications, the Core +API (`/core/v1`) for operators, and a machine API (`/api/v1`) for nodes and Runtime +daemons. Each has its own credential; one used elsewhere gets 401. The +[API index](/public-api) owns the full matrix of callers, credentials and routes. + +## Core + +Core is the only owner of durable execution facts: Projects and keys, Agents, +Sessions, Turns, Items, Environments, files and audit records, all in PostgreSQL. +It schedules Turns, handles cancellation and pending interactions, and checks that +a requested harness, Environment and capability combination is supported before +starting work. + +Core does not isolate tools, run a model or talk to a vendor SDK directly. It +selects implementations through interfaces and never branches on a harness, +operating system or provider name. See +[the decoupling principle](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/CONTRIBUTING.md#decoupling-principle) and the +[repository map](/development#repository-map). + +## Replaceable parts + +| Part | Responsibility | Connects through | Current implementations | Add one | +| --- | --- | --- | --- | --- | +| Sandbox Provider | Creates, bootstraps, renews and reclaims the outer Environment | `SandboxProvider` interface | Docker, microsandbox, E2B, sandbox nodes | [Sandbox Provider guide](/sandbox-provider) | +| Runtime | Prepares Skills, MCP and files, runs executors, owns local cleanup | Core–Runtime protocol over `/api/v1` | `oac-daemon`: managed Linux; self-hosted Linux, macOS and Windows | [Core–Runtime protocol](/runtime-protocol) | +| Harness | Runs the native model and tool loop | Harness adapter (`Executor` and `Turn`) | Codex, Claude Code, MiniMax Code | [Harness onboarding](/harness-onboarding) | +| Model Provider | Serves inference for the harness | Responses, Anthropic or Chat Completions protocol | Any endpoint speaking one of those protocols | [Model execution](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/model-execution.md) | + +Replaceability does not mean every combination works. Supported combinations are +declared as capabilities and validated explicitly; see +[Harness selection](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/harness-selection.md) and the +[coverage record](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/README.md). + +## A Session, end to end + +![A managed Session from creation to result](/images/source/docs/assets/architecture-session-flow.png) + +For a Core-managed (`openai_hosted`) Session: + +1. The application creates a Session through the Agents API. +2. Core asks the Sandbox Provider for an Environment. +3. The provider starts the Runtime using the [bootstrap contract](/runtime-bootstrap). +4. The daemon dials into Core and advertises its capabilities. +5. Core sends the preparation request; Runtime prepares Skills, MCP declarations + and initial files inside the Environment. +6. The application sends input. +7. Core prepares and starts execution on the daemon. +8. The daemon's harness adapter starts a native Turn. +9. The harness runs its model and tool loop against the model provider. +10. The daemon streams events, output and usage back to Core, then `done`. +11. The application reads Items and events from Core. + +A `self_hosted` Session skips steps 2 and 3: an administrator issues an executor +credential and you start the daemon on your own machine +([self-hosted guide](/self-hosted-execution)). A `none` Session uses an +existing device connection. Everything from step 4 onward is the same protocol. +The [Environment contract](/environments-and-files) covers +placement and expiry; the [Core–Runtime protocol](/runtime-protocol) defines +message order, receipts and failure ownership. + +## Boundaries to keep in mind + +- **Isolation belongs to the outer Environment.** The daemon is not a sandbox + ([Runtime and outer isolation](/concepts#runtime-and-outer-isolation)). +- **Execution and compute have separate lifetimes.** Closing an executor does not + release its allocation, destroy its Environment or delete its workspace. + Reclamation is an explicit Sandbox Provider operation. +- **Model keys stay with the compute that owns them.** A self-hosted Session brings + its own model provider ([why](/user-guide#which-model-provider-a-session-uses)). +- **Core Web is an administrator console.** It calls only `/core/v1` and cannot + start Sessions or send input ([Web architecture](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/architecture.md)). + +[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/architecture.md) diff --git a/apps/docs/content/docs/console.mdx b/apps/docs/content/docs/console.mdx index 76b682aa4..addbf0dee 100644 --- a/apps/docs/content/docs/console.mdx +++ b/apps/docs/content/docs/console.mdx @@ -52,7 +52,7 @@ through the management API. The browser signs in to the console with the Core ke only the console server sends it to Core. - [Connection and authentication](/bootstrap-projects-keys) -- [Architecture and ownership](/execution-model) +- [Architecture and ownership](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/architecture.md) - [Management interface coverage](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/protocol-coverage.md) - [Frontend handoff and acceptance](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/roadmap.md) - [React application](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/apps/web/README.md) diff --git a/apps/docs/content/docs/development.mdx b/apps/docs/content/docs/development.mdx index 7173802e1..2fa4bc7eb 100644 --- a/apps/docs/content/docs/development.mdx +++ b/apps/docs/content/docs/development.mdx @@ -93,7 +93,7 @@ site; `pnpm dev:docs` starts its development server. | `apps/parsar-daemon/internal/dispatch` | Runtime preparation, Executor reuse, Turn and cleanup ownership | [Harness lifecycle](/harness-onboarding#required-adapter-interfaces) | | `apps/parsar-daemon/internal/agent` | Native harness adapters | [Native references](/harness-onboarding#native-references) | | `services/agents-api/internal/sandbox` | Provider interfaces and managed compute lifecycle | [Provider onboarding](/sandbox-provider) | -| `services/core-console` | Console login and the server-side management proxy | [Web architecture](/execution-model) | +| `services/core-console` | Console login and the server-side management proxy | [Web architecture](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/architecture.md) | | `apps/web` and `packages/agents-client` | Console UI and typed clients | [Web guide](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/apps/web/README.md) | | `deploy/install` and `scripts` | Distribution, installation and validation tools | [Maintainers](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/maintainers.md) | | `contracts/agents-api` | Pinned schema, local semantic contracts and qualification evidence | [Coverage ledger](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/README.md) | diff --git a/apps/docs/content/docs/error-codes.mdx b/apps/docs/content/docs/error-codes.mdx new file mode 100644 index 000000000..015b4c698 --- /dev/null +++ b/apps/docs/content/docs/error-codes.mdx @@ -0,0 +1,297 @@ +--- +title: "Error codes" +description: "Every error code Core, the console and the machine transport write, and what each means." +--- + +This registry lists every error `code` Core, the console (including the +installer rejections it relays) and the daemon transport write, the response shapes that carry no code, and the codes the +TypeScript client creates itself. Operation-specific triggers and `param` values +stay in the resource contracts; this page says what each code means and where it +can appear. + +Two checks compare it with the code. `contract_conformance_test.go` in +`services/agents-api/internal/api` requires the status and code of every row to +be written somewhere and every written status and code to have a row, and the +statuses of the uncoded tables to equal the statuses their handlers write. +`apps/docs/scripts/verify-error-codes.mjs` does the same for client-generated +codes and for every code the client and Web compare against, and the Go test +also compares the installation domain setup codes with the installer. The +Namespaces column tokens are checked in both files: `all`, or the namespaces +whose routes can answer with the code. + +## Which "code" is meant + +The word names eight different things. Only the first three are HTTP error codes. + +| Layer | Where it appears | Examples | Reference | +| --- | --- | --- | --- | +| API envelope | `error.code` of a `/v1`, `/core/v1` or `/api/v1` JSON error, or of an error object inside a Session event | `invalid_request_error`, `project_archived`, `stream_interrupted` | [HTTP API codes](#http-api-codes), [Session event codes](#session-event-error-codes) | +| Console envelope | `error.code` of an error Web's server writes for `/core/*` | `console_sign_in_required`, `core_unreachable` | [Console codes](#console-codes), [Core errors](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md) | +| Daemon transport | `error` member of an `/api/v1/agent-daemon/*` JSON error | `missing_bearer`, `incompatible_version` | [Runtime daemon transport codes](#runtime-daemon-transport-codes) | +| Runtime protocol result | `error_code` of a Core–Runtime message after connection, such as a workspace, preparation or cancellation result; Core validates each value against its message and maps it to its own outcome or stored cause; no API response returns it | `write_rejected`, `read_unconfirmed`, `cancel_timeout` | [Core–Runtime protocol](/runtime-protocol) and its typed payloads; not listed here | +| Node diagnostic | `diagnostic` value inside a node payload; never an HTTP status | `docker_unavailable`, `kvm_unavailable` | [Sandbox deployment](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/sandbox-deployment.md), [nodes](/hosted-providers) | +| Session diagnostic category | `code` of a failure category inside a successful Session diagnostics snapshot | `harness_error`, `runtime_disconnected` | [Diagnostic failure categories](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md#diagnostic-failure-categories) | +| Turn error | `error.code` of a failed Turn or subagent Turn in a successful read; Core always publishes `internal_error`, and the other values of the pinned enum are never returned | `internal_error` | The cause is in the [diagnostic failure categories](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md#diagnostic-failure-categories); not listed here | +| Client identifier | `AgentCoreError.code` created by `packages/agents-client` without a response, or a local daemon/adapter error | `sandbox_configuration_unconfirmed`, `invalid_admin_response` | [Client-generated codes](#client-generated-codes), daemon and adapter guides | + +`error.type` is not a second code. It follows one rule: `server_error` for any 5xx, +`conflict_error` for any 409, `not_found_error` or `invalid_beta` when the code is +that value, and `invalid_request_error` otherwise. + +## HTTP API codes + +`/v1`, `/core/v1` and `/api/v1` share one writer, so a code keeps its meaning in +every namespace; a row names a namespace-specific trigger where one differs. `/core/v1` adds optional `details` ([Core errors](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md)). +Clients branch on `code`, never on `message`. A `null` row is a response whose +`code` is null. + +| Status | Code | Namespaces | Meaning | +| --- | --- | --- | --- | +| 400 | `invalid_request_error` | all | Request validation failed: body fields, list queries on Agents API Beta lists and on the Core resource lists under `/projects/{project_id}`, cursors, MCP credential selection or unstorable text. `param` names the field when known | +| 400 | `invalid_request` | all | Malformed body, identifier or local request limit outside the official fields, including invalid queries on the Core Project, key, audit log and summary lists | +| 400 | `invalid_value` | `/v1`, `/core/v1` | Skills: invalid `order` or Skill version `after` on `/v1`; on both namespaces, deletion of the default Skill version (param `version`) | +| 400 | `duplicate_parameter` | `/v1` | Skills list key supplied more than once; `param` is the key | +| 400 | `integer_below_min_value` | `/v1` | Skills list `limit` below 0 | +| 400 | `integer_above_max_value` | `/v1` | Skills list `limit` above 100 | +| 400 | `unsupported_parameter` | `/v1`, `/core/v1` | A body on a deletion that accepts none, a repeated Files list key, or query parameters Runtime observation and history reads do not accept | +| 400 | `invalid_beta` | `/v1` | Missing or wrong `OpenAI-Beta: agents=v1` on an Agents API Beta route | +| 400 | `unsupported_or_invalid_configuration` | `/v1` | The configuration or input is outside what the selected harness supports | +| 400 | `model_provider_required` | `/v1` | The Session resolved no model provider and cannot run | +| 400 | `invalid_sandbox_configuration` | `/core/v1` | Sandbox deployment configuration is invalid | +| 400 | `invalid_name` | `/core/v1`, `/api/v1` | A Project, key or node name, including the name a node enrolls with, fails its length or character rules; on `/core/v1`, `details.max_length` gives the limit | +| 400 | `invalid_node_capacity` | `/core/v1` | Node `max_active` or `max_retained` is outside 1-1000000, or retained is below active | +| 400 | `invalid_model_provider` | `/core/v1` | The model configuration body is missing or malformed; a complete bundle is required | +| 400 | `model_provider_base_url_invalid` | `/core/v1` | `base_url` is not HTTPS, or carries credentials, a query or a fragment | +| 400 | `model_provider_protocol_unsupported` | `/core/v1` | The protocol is unknown or unsupported by the harness; `details.allowed_protocols` lists the supported ones | +| 400 | `model_provider_api_key_invalid` | `/core/v1` | The key is empty, longer than 16384 characters or contains a prohibited character | +| 400 | `model_provider_token_limits_invalid` | `/core/v1` | `context_window` or `max_output_tokens` is invalid, or missing where the harness requires it | +| 400 | `model_configuration_model_invalid` | `/core/v1` | `model` is not a nonempty model identifier | +| 400 | `harness_config_invalid` | `/core/v1` | `harness_config` contains unsupported or invalid native model parameters | +| 400 | `e2b_api_key_invalid` | `/core/v1` | E2B rejected the API key (param `e2b.api_key`) | +| 400 | `e2b_template_build_invalid` | `/core/v1` | The E2B template build is not a ready immutable build with matching resources (param `e2b.template`) | +| 400 | null | `/v1`, `/core/v1` | Files list range and order errors on `/v1`, an unknown Files `purpose` filter (param `purpose`) on both namespaces, and public download of a `user_data` File | +| 401 | `invalid_api_key` | `/v1` | Files or Skills rejected a supplied Bearer Project API key | +| 401 | `invalid_admin_key` | `/core/v1` | The Core key is missing or wrong | +| 401 | `invalid_node_credential` | `/api/v1` | The node enrollment token or node credential is missing or wrong | +| 401 | `installation_authorization_invalid` | `/api/v1` | The native installation authorization is invalid or expired; get a new command from the Session | +| 401 | null | `/v1` | No valid Bearer Project API key on an Agents API Beta route, or none supplied to Files or Skills | +| 404 | `not_found_error` | `/v1`, `/core/v1`, `/api/v1` | The resource does not exist in the caller's or the selected Project's tenant, or the Environment of a native installation no longer exists | +| 404 | `not_found` | `/core/v1` | Unknown Core operation, unknown harness, or a harness without a deployment default model provider | +| 404 | `unsupported_operation` | `/v1` | Unknown `/v1` operation | +| 404 | null | `/v1` | Missing File or Skill on the public Files and Skills routes | +| 405 | `unsupported_operation` | all | Method not allowed, including HEAD on content downloads and Runtime reads | +| 409 | `conflict_error` | `/v1`, `/core/v1` | Official conflicts: Session not idle for deletion, pending input, MCP credential ambiguity, hosted environment failure or a different tool result | +| 409 | `turn_conflict` | `/v1` | The Session or Turn cannot accept this change in its current state, such as an Environment file write while Session input is pending | +| 409 | `idempotency_conflict` | `/v1`, `/api/v1` | The Idempotency-Key was used with different input; on sandbox node enrollment, the node ID is already enrolled | +| 409 | `environment_unavailable` | `/v1` | The Environment no longer accepts new input | +| 409 | `environment_input_expired` | `/v1` | The Environment input deadline passed before admission | +| 409 | `environment_input_cancelled` | `/v1` | The Environment input was cancelled before admission | +| 409 | `project_exists` | `/core/v1` | The Project ID already exists | +| 409 | `project_api_key_exists` | `/core/v1` | The API key ID already exists; list its metadata and revoke it if the secret was not saved | +| 409 | `project_archived` | `/core/v1` | The target Project is archived | +| 409 | `executor_credential_exists` | `/core/v1`, `/api/v1` | The executor key ID already exists; rotate it explicitly to replace the secret. On the native installation claim, the Environment already has another, rotated or revoked executor credential | +| 409 | `runtime_history_unsupported` | `/core/v1` | Runtime history is not supported for this Session | +| 409 | `sandbox_deployment_conflict` | `/core/v1`, `/api/v1` | The sandbox deployment cannot change in its current state | +| 409 | `sandbox_configuration_error` | `/core/v1` | The deployment cannot be served as configured, for example E2B with a loopback public URL | +| 409 | `sandbox_node_address_mismatch` | `/core/v1`, `/api/v1` | The node uses a different Core address than the installation public URL | +| 409 | `sandbox_specification_mismatch` | `/core/v1`, `/api/v1` | The node's resource limits or Runtime release do not match the active deployment | +| 409 | `runtime_node_in_use` | `/core/v1` | The node still holds allocations, snapshots, reservations or pending cleanup | +| 409 | `runtime_local_node_configured` | `/core/v1` | The local node is enabled in deployment configuration and cannot be removed | +| 409 | `sandbox_generation_stale` | `/core/v1` | The deployment generation changed; `details.current_generation` gives the new one. Refresh before submitting again | +| 409 | `sandbox_reset_required` | `/core/v1` | The change needs a reset first, such as another backend or E2B team; `details` names both providers | +| 409 | `sandbox_in_use` | `/core/v1` | Hosted sandbox resources still belong to the deployment; `details.allocations` and `details.pending` count them | +| 409 | `sandbox_reset_in_progress` | `/core/v1`, `/api/v1` | A sandbox reset is in progress, so the deployment cannot change and nodes cannot enroll or read their configuration | +| 409 | `sandbox_not_configured` | `/core/v1` | The operation needs a configured sandbox deployment | +| 409 | `e2b_team_mismatch` | `/core/v1` | The E2B key cannot manage the retained deployment; reset before changing teams (param `e2b.api_key`) | +| 413 | `request_too_large` | all | The body exceeds the operation's limit, or an uploaded File or Skill exceeds its content limit | +| 500 | `internal_error` | all | An unexpected persistence failure; no detail is exposed | +| 503 | `authentication_unavailable` | `/v1` | Project API key authentication is temporarily unavailable; written before any operation runs | +| 503 | `execution_unavailable` | `/v1`, `/core/v1` | Execution or Core Runtime observation is not available on this service, or a Core Runtime observation list exceeded its request budget | +| 503 | `stream_unavailable` | `/v1` | Live events or streaming creation are unavailable | +| 503 | `credential_storage_unavailable` | `/v1`, `/core/v1` | Credential encryption is not configured | +| 503 | `file_storage_unavailable` | `/v1`, `/core/v1` | Source File storage is not configured | +| 503 | `file_transfer_unavailable` | `/v1`, `/core/v1` | The bounded transfer deadline cannot be set for an upload or download | +| 503 | `skill_storage_unavailable` | `/v1`, `/core/v1` | Skill storage is not configured | +| 503 | `artifact_storage_unavailable` | `/v1`, `/core/v1` | Artifact storage is not configured | +| 503 | `subagent_storage_unavailable` | `/v1` | Subagent storage is not configured | +| 503 | `execution_configuration_unavailable` | `/core/v1` | Session execution configuration cannot be read | +| 503 | `runtime_history_unavailable` | `/core/v1` | Durable Runtime history is not configured or temporarily unavailable | +| 503 | `core_metrics_unavailable` | `/core/v1` | Core metrics are not configured or could not be read | +| 503 | `runtime_node_unavailable` | `/v1`, `/core/v1`, `/api/v1` | The selected sandbox node is unavailable, or no node has capacity for a new hosted Session | +| 503 | `sandbox_credential_unavailable` | `/core/v1`, `/api/v1` | Sandbox credentials cannot be decrypted; check the service credential encryption configuration | +| 503 | `sandbox_reset_in_progress` | `/v1` | Hosted admission is paused while a sandbox reset runs; nothing was admitted | +| 503 | `sandbox_nodes_preparing` | `/v1` | The nodes with free capacity are still preparing the deployment's Runtime | +| 503 | `e2b_request_unconfirmed` | `/core/v1` | E2B verification could not be confirmed; nothing is replayed | +| 503 | `provider_unavailable` | `/core/v1` | E2B template discovery is unavailable; check the credential, endpoint and connection | +| 503 | `diagnostics_unavailable` | `/core/v1` | The Session diagnostics reader is not configured | +| 503 | `installation_unavailable` | `/api/v1` | Matching native installation artifacts are unavailable on this Core | + +The namespace column shows where each code is expected. Codes from the shared +stored-error mapping can appear on any operation whose storage reports that +condition. No 503 carries `Retry-After`. + +Core's reverse-path canonicalization answers a path that cannot be decoded with a +plain-text 400 before any namespace is selected; a parsed request path always +decodes, so this is not expected in practice. + +## Session event error codes + +These codes appear inside Session events, in a live stream that has already +answered 200 and in the saved event history. Core's own interruption is an +`event: error` frame whose `error` object has `code`, `type` and `message` but no +`param`. A hosted provisioning failure records the pinned `error` event, with a +null `param`, and the Environment state `error` of +`agent.session.environment.failed`, which has no `param`. See +[history, events and usage](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/history-events-usage.md). + +| Status | Code | Meaning | +| --- | --- | --- | +| 200 | `stream_interrupted` | The live stream was interrupted; reconnect, then read the Session and its saved Items to recover | +| 200 | `sandbox_error` | `error` event, type `environment_error`: the hosted Environment failed to provision; the message is a safe reason without command output | +| 200 | `environment_connection_failed` | Environment state error, type `environment_error`, in `agent.session.environment.failed` | + +## Console codes + +Web's server writes these for `/core/*` requests it rejects before forwarding, +and for the console-local `POST /console/installation/domain` HTTPS setup request. +See [Core errors](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md#console-generated-failures) and +[Web request boundaries](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/architecture.md#request-boundaries). + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | `console_request_invalid` | Request path, method or upgrade is unsafe | +| 400 | `domain_setup_unavailable` | Domain setup: this installation uses an external reverse proxy, so HTTPS is configured there | +| 400 | `invalid_request` | Domain setup: the request body exceeds 2 KiB | +| 401 | `console_sign_in_required` | Console session is missing or expired | +| 403 | `console_origin_rejected` | Host, Origin or Fetch Metadata checks failed | +| 502 | `core_unreachable` | Core transport failed or Core tried to redirect | +| 502 | `installation_unreachable` | Domain setup: the installer did not answer or returned an invalid or 5xx response; run `oac status` on the server | + +## Installation domain setup codes + +`POST /console/installation/domain` relays these installer rejections unchanged +in `{"error":{"code":"…","message":"…"}}`. The installation controller in +`deploy/install/ingress.py` writes them; see [Web management](/admin-api) +and the [installer contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/maintainers.md#managed-https-ownership). +Failures after the `202` acceptance are reported through the status `message`, +not as codes. + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | `domain_setup_unavailable` | Managed HTTPS needs a combined Docker installation | +| 400 | `invalid_hostname` | The installer's hostname validation rejected the value | +| 400 | `invalid_confirmation` | `confirm_public_url_change` does not equal the new HTTPS URL | +| 400 | `invalid_request` | The body is missing, larger than 2 KiB, not JSON or has other members | +| 401 | `unauthorized` | The installer rejected the console's Core key | +| 409 | `configuration_pending` | `config.json` has pending edits; apply or revert them first | +| 409 | `installation_not_ready` | The installation has not been applied yet | +| 409 | `installation_not_running` | Core, Web, the gateway or the installation service is not running | +| 409 | `generated_files_edited` | Generated files were edited by hand; resolve them with `oac apply` | +| 409 | `public_url_confirmation_required` | The address changes existing bindings; resubmit with `confirm_public_url_change` | +| 409 | `installation_busy` | Another installation operation holds the lock, or the installer rejected the change | + +## Console sign-in responses + +`/console/auth`, `/console/auth/login`, `/console/auth/logout` and the other +signed-in console pages outside `/core/*` answer failures as +`{"error":""}` with no code. Clients branch on the status. + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | null | The login body is not a JSON object with only a non-empty `core_key` | +| 401 | null | Wrong Core key, or a console page requested without a session | +| 403 | null | Host, Origin or Fetch Metadata checks failed outside `/core/*` | +| 404 | null | Unknown `/console/auth/*` route | +| 405 | null | Login or logout without POST (`Allow: POST`) | +| 415 | null | The login body is not `application/json` | +| 429 | null | Sign-in is busy (`Retry-After: 1`) or ten failed attempts in one minute (`Retry-After: 60`) | +| 503 | null | A session token could not be generated | + +Outside `/core/*` the console also answers an unsafe path with a plain-text 400, +a wrong method on static pages and `/node-install/*` with a plain-text 405 +(`Allow: GET, HEAD`), and unknown or direct `/v1` and `/api/v1` paths with a +plain-text 404. After sign-in, `/core` and `/core/*` paths outside `/core/v1` +also get a plain-text 404, `/console/api-keys` and its subpaths a plain-text 404, +and `/console/installation/domain` with a method other than GET or POST a +plain-text 405 (`Allow: GET, POST`). `GET /healthz` returns `200 ok` without +authentication. + +## Runtime daemon transport codes + +`/api/v1/agent-daemon/ws`, `/bootstrap` and `/device-status` answer the failures +their handlers detect as `{"error":"","detail":""}`. `detail` is +diagnostic text, not a stable value. The router in front of them answers an +unknown `/api/v1/agent-daemon/*` path with a plain-text 404 and a wrong method with +an empty 405, and a failed WebSocket handshake on `ws` is answered as plain text by +the WebSocket library, so clients must not assume the JSON body on every +failure. + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | `missing_params` | `device_id`, `version` or the Bearer credential is missing | +| 400 | `missing_device_id` | The bootstrap body or device-status query has no `device_id` | +| 400 | `bad_json` | The bootstrap body is not valid JSON | +| 401 | `missing_bearer` | No Bearer daemon credential | +| 401 | `unknown_device` | The device is not enrolled | +| 401 | `bad_credential` | The daemon credential does not match the device | +| 403 | `wrong_runtime_type` | The credential belongs to another Runtime type | +| 405 | `method_not_allowed` | Bootstrap without POST, if the handler is reached; the router's empty 405 normally answers first | +| 426 | `incompatible_version` | The daemon version is not supported by this Core | +| 500 | `internal` | Authentication failed unexpectedly | + +## Plain-text transport responses + +These routes answer failures with a `text/plain` body and no code. + +| Status | Code | Routes | Meaning | +| --- | --- | --- | --- | +| 400 | null | `POST agent-daemon/enroll`, `GET agent-daemon/connection` | Invalid body or query | +| 401 | null | enroll, connection, `GET sandbox-node/connect` | Missing or rejected credential | +| 405 | null | enroll, connection | Wrong method (`Allow` names the method) | +| 409 | null | enroll, connection, sandbox-node/connect | The Environment is bound to another executor, or the node identity is already connected | +| 503 | null | enroll, connection, sandbox-node/connect | Enrollment storage, node authentication or the connection owner is unavailable | + +The public installer artifacts under `/api/v1/agent-daemon/install/{version}/` +answer a method other than GET or HEAD with an empty 405 and an unknown file with +a plain-text 404. + +## Client-generated codes + +`packages/agents-client` creates these `AgentCoreError` codes itself; Core never +sends them. + +Codes that report a malformed response use status 502 (or 0 for Core metrics) +and mean the client rejected what Core returned; they never indicate a request +error. + +| Code | Meaning | +| --- | --- | +| `invalid_admin_response` | An administration or sandbox administration response has the wrong shape (`AdminClient`, `SandboxAdminClient`) | +| `invalid_response` | A Core metrics response has the wrong shape (`CoreMetricsClient`) | +| `sandbox_configuration_unconfirmed` | A sandbox configuration write failed without a confirmed outcome, or its reason was withheld because it could echo the key; refresh before submitting again | +| `credential_write_failed` | A Vault credential write was rejected; the client keeps the status but never parses the body, which could reflect the secret | +| `invalid_environment_template` | An Environment Template response has the wrong shape | +| `invalid_environment_template_list` | An Environment Template list has the wrong shape | +| `invalid_vault_resource` | A Vault response has the wrong shape or another ID | +| `invalid_vault_list` | A Vault list has the wrong shape | +| `invalid_vault_deletion` | A Vault deletion receipt has the wrong shape or another ID | +| `invalid_vault_credential` | Credential metadata has the wrong shape or another ID | +| `invalid_vault_credential_list` | A Credential list has the wrong shape | +| `invalid_vault_credential_deletion` | A Credential deletion receipt has the wrong shape or another ID | +| `invalid_session_vaults` | A Session's Vault attachments have the wrong shape | +| `invalid_environment_resource` | An Environment response has the wrong shape | +| `invalid_environment_file` | An Environment file response has the wrong shape | +| `invalid_environment_files` | An Environment files page has the wrong shape | +| `invalid_session_resource` | A Session response has the wrong shape | +| `invalid_session_list` | A Session list has the wrong shape | +| `invalid_history_resource` | A Turn, Item or other history response has the wrong shape | +| `invalid_runtime_observation` | A Runtime observation has the wrong shape | +| `invalid_stream_event` | An event stream frame has the wrong shape | +| `empty_stream` | An event stream closed before its first event | +| `invalid_source_file` | Source File metadata has the wrong shape | +| `invalid_source_file_list` | A Files list has the wrong shape | +| `invalid_source_file_content` | Source File content is incomplete or has the wrong headers | +| `invalid_skill_resource` | A Skill or Skill version response has the wrong shape | +| `invalid_skill_content` | Skill content is incomplete or has the wrong headers | + +[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/error-codes.md) diff --git a/apps/docs/content/docs/execution-model.mdx b/apps/docs/content/docs/execution-model.mdx deleted file mode 100644 index 003336f41..000000000 --- a/apps/docs/content/docs/execution-model.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "Execution and API architecture" -description: "Applications call the public API; the administrator browser calls Web; Runtime connects to Core." ---- - -![Application, administration and machine credential boundaries](/images/architecture.svg) - -Core Web manages a Core deployment. Applications, including Parsar, use the public -Agents API independently with their own Project keys. The management backend, -`AdminClient` and the React console built on them are implemented. - -The [design principles](/concepts) define identity and authority. -The [administrator contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/admin-api.md) defines exact -routes, payloads, pagination and audit records. - -## Request boundaries - -```mermaid -flowchart LR - browser["Administrator browser"] - console["Core console service"] - core["Core API"] - database[("PostgreSQL")] - application["Application / official SDK"] - runtime["Runtime and native adapters"] - - browser -->|"Same-origin management requests; console login"| console - console -->|"/core/v1/* by prefix, including sandbox; Core key"| core - application -->|"/v1; Project API key"| core - core <--> database - core <--> runtime -``` - -React management code must use the Core clients from `packages/agents-client`: -`AdminClient` for `/core/v1`, `CoreMetricsClient` for `/core/v1/metrics` and the -sandbox management client for `/core/v1/sandbox`. The console service -returns 404 for `/v1` and `/api/v1`, including requests with an explicit Bearer -token. It has no application key and does not impersonate the selected Project. - -The console signs the browser in with the Core key, checks the host and origin, and -forwards every signed-in `/core/v1/*` request to Core by prefix; Core alone decides -whether the route exists. It strips the browser's Authorization, Cookie, Origin and -Referer headers and supplies the Core key as its private upstream credential. Core -rejects application keys on management routes and the Core key on `/v1`. -The audit actor label is declared by the caller and is display only, never Core authorization: the console server declares `console`, and operator scripts calling Core with the Core key directly leave it empty. - -`GET` and `POST /console/installation/domain` are the scoped installation-management -exception: the console authenticates the same browser session and origin, then -calls the installer's private Unix socket with its server-held Core key. This is -not a Core `/core/v1` route and does not use `AdminClient`. It can configure only -the managed domain; it cannot submit shell commands or arbitrary process settings. -The [installer rules](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/maintainers.md#managed-https-ownership) own application, -certificates and recovery. Before a domain is configured, the console accepts -same-origin HTTP requests at literal IP addresses; after apply, only the configured -HTTPS origin is accepted. - -Node and daemon connections use `/api/v1` with their own credentials. The reverse -proxy sends them directly to Core; the console never forwards them, and they do not -grant a browser execution authority. - -## Ownership - -| Component | Responsibility | -| --- | --- | -| React frontend | Project selection, permitted management actions and operational views; cached reads (TanStack Query) that keep the last data on screen while refreshing | -| `AdminClient` | Typed management requests and validation, sharing resource parsers with the public client | -| `services/core-console` | Core key login, host/origin checks, and prefix forwarding of `/core/v1/*` with the Core key as the private upstream credential | -| Core API and PostgreSQL | Project isolation, resource state, deletion preconditions, audit and scheduling | -| Runtime and native adapters | Existing allocation, process lifecycle and execution protocols | - -Projects, keys and administrator authority follow the -[design principles](/concepts#projects-own-assets). The console adds -no execution path: a deletion conflict is never resolved by an implicit cancellation. - -Secret fields remain write-only; Skill source and Artifact content have explicit -read routes, while Source File content does not have an administrator download -route. - -## Deployment and application Runtime paths - -Deployment sandbox management selects one provider at a time: E2B, Docker or -microsandbox. E2B uses the deployment's provider integration; Docker and microsandbox -use operator-managed machines. Provider setup, reset and node administration -belong to the existing sandbox management surface. - -An application's `self_hosted` Runtime, including one it provisions in its own E2B -account, is a separate caller-managed path. It does not choose or reconfigure the -deployment provider. This console contract changes neither native Runtime protocols -nor application Session creation semantics. - -## Frontend state and validation - -Session inspection uses paginated durable history and bounded polling. There is no -management Session SSE endpoint. Project changes must discard stale reads and -pending operation state before displaying results in another Project. - -The client sends each write once per explicit action. An uncertain result stays -visible until the administrator checks state and decides how to proceed. Issued -key plaintext must not enter browser storage or logs. Key issuance recovery -follows the administrator contract. - -The sandbox deployment read (`GET /core/v1/sandbox/deployment`) describes the saved -selection. It does not prove a reachable model, valid provider credentials or -execution readiness. Runtime observations, usage coverage and audit history must -retain the distinctions defined by Core. In E2B views, the running sandbox count -comes from the deployment's allocations; the hosted Runtime total counts hosted -observation records across projects and reported lifecycle states. These sources -have different coverage and refresh independently, so the console does not infer -resource retention or cleanup from their difference. -Native execution ownership remains governed by [CONTRIBUTING.md](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/CONTRIBUTING.md). - -[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/architecture.md) diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx index 9c86b0981..538fc286a 100644 --- a/apps/docs/content/docs/index.mdx +++ b/apps/docs/content/docs/index.mdx @@ -5,7 +5,7 @@ description: "Install Core and Web, create a Project API key, and add execution OpenAgentCore runs AI agents on your own infrastructure behind the OpenAI Agents API. Pick the path that matches your role. New here? Read the -[architecture overview](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/architecture.md) first. +[architecture overview](/architecture) first. ## Operators: install and run diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json index 7ff7f2f37..9a05f29dd 100644 --- a/apps/docs/content/docs/meta.json +++ b/apps/docs/content/docs/meta.json @@ -4,7 +4,7 @@ "---Start here---", "index", "concepts", - "execution-model", + "architecture", "install", "install-options", "configure", @@ -13,6 +13,7 @@ "quickstart", "user-guide", "public-api", + "request-conventions", "agents-and-tools", "sessions", "examples", @@ -24,6 +25,7 @@ "---Administration---", "console", "admin-api", + "error-codes", "observability", "troubleshooting", "api-reference", diff --git a/apps/docs/content/docs/public-api.mdx b/apps/docs/content/docs/public-api.mdx index ca6557cd6..bb8da4d74 100644 --- a/apps/docs/content/docs/public-api.mdx +++ b/apps/docs/content/docs/public-api.mdx @@ -20,7 +20,8 @@ A credential used in another namespace gets 401: a Project API key on `/core/v1` **Routing.** The reverse proxy sends `/v1` and `/api/v1` to Core and everything else to Web ([proxy setup](/install#https-and-the-reverse-proxy)). Browsers reach `/core/v1` only through Web's server, which adds the Core key after -sign-in; Web returns 404 for `/v1` and `/api/v1`. Operator scripts call `/core/v1` +sign-in; Web returns 404 for `/v1` and `/api/v1`, and answers an unauthenticated +`GET /healthz` liveness probe with `200 ok`. Operator scripts call `/core/v1` on Core's loopback port. Details: [Web and Core](/admin-api). ## Public API @@ -28,7 +29,8 @@ on Core's loopback port. Details: [Web and Core](/admin-api). Applications call `/v1` with a Project API key. The routes are exactly the 58 pairs in [upstream-routes.json](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/upstream-routes.json). The [Agents API guide](/sessions) explains every resource with SDK and HTTP -examples. +examples. [Request conventions](/request-conventions) covers the headers, JSON body +checks and list parameters every `/v1` operation shares. ## Core API @@ -93,6 +95,16 @@ the Core key or a Project API key. | `POST agent-daemon/enroll`, `GET agent-daemon/connection` | Self-hosted executor and its installer | Executor credential from `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials` | [Executor credentials](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-executor-credentials.md) | | WebSocket `GET agent-daemon/ws`, `POST agent-daemon/bootstrap`, `GET agent-daemon/device-status` | Runtime daemons | Daemon credential: Core writes one into each hosted sandbox it prepares; a self-hosted executor uses its executor credential | [Runtime enrollment](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/README.md#user-managed-runtime-enrollment) | +Only the three `sandbox-node` HTTP routes and the two native installation routes +(`agent-daemon/installation` and its `/claim` subroute) are in the machine OpenAPI +and use the JSON error envelope. The node WebSocket and the daemon transport are served +beside the API router: `agent-daemon/enroll`, `agent-daemon/connection` and +`sandbox-node/connect` answer failures with a plain-text body and no code, and +`agent-daemon/ws`, `bootstrap` and `device-status` answer the failures their +handlers detect with `{"error":"","detail":"…"}`; router and WebSocket +handshake failures stay plain text. Both are listed in the +[error code registry](/error-codes#runtime-daemon-transport-codes). + ## Contract sources - [Pinned upstream baseline](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/upstream.json): OpenAI @@ -135,6 +147,12 @@ ownership and platform rules. The console-local `GET`/`POST /console/installation/domain` surface uses the signed-in browser session and same-origin checks. It delegates only domain setup to the installer, with the server-held Core key over a private Unix socket; it is not part -of the Agents API or Core management API. See [Web request boundaries](/execution-model#request-boundaries). +of the Agents API or Core management API. See [Web request boundaries](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/web/architecture.md#request-boundaries). + +Core administration failures use the [Core error envelope](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md), +including typed optional safe details and distinct console proxy rejection codes. +The [error code registry](/error-codes) lists every error +code in all three namespaces, the console and the daemon transport, and is checked +against the code. [Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/api/README.md) diff --git a/apps/docs/content/docs/request-conventions.mdx b/apps/docs/content/docs/request-conventions.mdx new file mode 100644 index 000000000..547aef585 --- /dev/null +++ b/apps/docs/content/docs/request-conventions.mdx @@ -0,0 +1,74 @@ +--- +title: "Request conventions" +description: "Headers, JSON body checks, list parameters and errors shared by every /v1 operation." +--- + +These rules apply to every `/v1` operation. An operation page adds only what that +operation does differently, and repeats a rule from above where the operation's own +description states it: the Files and Skills operations repeat the `OpenAI-Beta` rule, +and Create a reusable Agent repeats the JSON body checks. + +## Headers + +| Header | Rule | +| --- | --- | +| `Authorization` | `Bearer ` on every operation. See [API namespaces and credentials](/public-api). | +| `OpenAI-Beta` | Exactly one `agents=v1` value on every operation except Files (`/files`) and Skills (`/skills`). Otherwise 400 `invalid_beta`. The pinned SDK sends it. | +| `OpenAI-Organization`, `OpenAI-Project` | Optional. If present they must be `core` and `proj_`; otherwise the request gets the same 401 as a rejected key. | +| `Idempotency-Key` | Optional on Session creation and on event submission, up to 128 bytes. A Core extension: a retry with the same key and request returns the original result, and the same key with a different request returns 409 `idempotency_conflict`. A streamed Session creation retry is the exception; see Create an execution Session. The hosted service returned distinct Sessions for repeated creation keys; its event submission behavior is not documented. | + +## JSON request bodies + +Every operation with a JSON body checks it in this order, before any field +validation or resource lookup: + +1. The `Content-Type` must be `application/json` or another `application/*+json` + type, case-insensitive, with well-formed parameters. +2. The body must fit the operation's limit: 1 MiB, or 16 MiB for Session creation and + for creating or updating an Environment Template. Environment file uploads have + their own limits. A larger body returns 413 `request_too_large` with a Core + message naming the limit. +3. The body must be valid UTF-8 and one JSON value, with no unpaired surrogate + escape and no repeated key at any depth, and its root must be an object. An empty + body or `null` is treated as `{}`. + +Failures of checks 1 and 3 return 400 `invalid_request_error` with a null `param` +and the official message. + +Updating a Skill's default version (`POST /v1/skills/{skill_id}`) is the one +exception: it reads its body without these checks, up to 64 KiB, and an unreadable +body returns 400 `invalid_request`. + +Member names match exactly; a case variant is an unknown member. Text that contains +U+0000 or cannot be stored as UTF-8 returns 400 `invalid_request_error`. This is a +limit of Core's storage, not of the official API. + +## Lists + +Lists take `after`, `limit` and `order`; the Environment files list takes `path`, +`limit` and `order` and continues with an opaque `page` token instead of `after`. `order` is `asc` or `desc`; omitting it uses the +operation's default, and an explicitly empty value is invalid. Unknown query keys +are ignored, and a supported scalar key given twice is rejected. Array parameters, +such as the Vault and Credential `status[]` filter, may repeat. + +The `limit` bounds, the default order and the fields of each error differ between +the Agents API lists, Files and Skills. Each operation page states its bounds and how +an unresolved `after` cursor fails. The +[list query record](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/list-query-semantics.md) has the +evidence for each family. + +## Errors + +Clients branch on the HTTP status and `error.code`, never on `message`. The +[error code registry](/error-codes) lists every code. + +## Compatibility notes + +Core implements the pinned OpenAI Agents API. Where an operation page says a +behavior is not yet verified against the hosted service, Core's behavior is +documented but has not been compared with the official service. The +[coverage record](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/README.md) and +[operation evidence](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/operation-evidence.md) hold the +details and the request evidence. + +[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/api/request-conventions.md) diff --git a/apps/docs/content/guide-sources.json b/apps/docs/content/guide-sources.json index 3bb814ba3..8bfe65b3e 100644 --- a/apps/docs/content/guide-sources.json +++ b/apps/docs/content/guide-sources.json @@ -3,13 +3,17 @@ "sources": { "docs/getting-started/README.md": "d46e1b6cd0693a282f504297c87df6ddf26b99ce8c7afdb613666acd836767f5", "docs/design-principles.md": "21a05fb089804db6fab5674ec9a6cf849a3affedad2ca927a38d9b46eeec9a50", - "docs/web/architecture.md": "7d5daf7745d2a25bf1113eea48512b085137f4f806c3fa0b6b16af63f7b18c4e", + "docs/assets/architecture-overview.png": "c6103e2a8730796a15d6c4ae7165f3b9e60dbd09075b459d34821a3ee0d2d49f", + "docs/assets/architecture-api-surfaces.png": "37c0d0d4f42c37ec41f8d4931ef10f182287d94d0928da195bf8b9e377c942e5", + "docs/assets/architecture-session-flow.png": "0f0a78c43d3dfd235f3994421708c65347863665278bd39e79d19b52e13fab7a", + "docs/architecture.md": "dff0924e6f9212f781b44b92e40a3359f68ffed86ab4885557d053df75c0829e", "docs/getting-started/install.md": "84b21002136acd4f006392685b7a071323336e87c1aac6e3c23ca56acb40833c", "docs/getting-started/install-options.md": "e03487bb6d978f84c596467028e25fd99fdc21cf2060af24ceb68df885084798", "docs/configuration.md": "7dc0031145bb5811bf22cab15270b511b1c43b1bd1ee2b71175d3bc848751bd6", "docs/web/core-connection.md": "861c75c32676fd17b84eb356b263096703af5750c1ceb71bb339e84607fffc56", "docs/getting-started/quickstart.md": "b989682ac2e58d59a794118fd371b37d1ea64c957d3512ff53739458a95d0f9a", - "docs/api/README.md": "dbe3f172a997ee2fd3d2e5765d382b4fb7cf7c50f1dd17212ab9646f6959d63e", + "docs/api/README.md": "878a540c3876f703d5e1ded36a2cee7ca462f80b27627897135ac981246fe9f3", + "docs/api/request-conventions.md": "3e5e96350ab6fcf24457ece52fb9a582479ddb157cebbf34cc1cf13a22b09ba8", "contracts/agents-api/execution-tools.md": "8cc0dbe207e8e80ac104bf482c37ea297cd64250b51d288ed4baf553756424d2", "docs/api/public-agent-api.md": "00979732412a971013e8f01b4c74820ff51aafdded6b0f105d25a78af86a6627", "docs/examples.md": "0e1bdaeff51c9c36779f817be31ea9816b7d8cb2290cf8350d3c4801f436f4f9", @@ -20,6 +24,7 @@ "apps/web/public/onboarding/monitor-en.webp": "29dc220cb1250c7016b7c4bf7f30e9510b07c07b814a48c3aa9303b2d76f20b2", "docs/web/README.md": "47159689b2488f0a94a1af8488bcf98b465e0cca4003d64a4699d7b4db24e086", "docs/api/web-management.md": "fe24e883f5745d262d3bd88eb73ae2cbbb723297b9a237f28849f9e3b50dffd4", + "contracts/agents-api/error-codes.md": "89fcc0b2017d480eddf1474636d560a2fafabdd7cb7a5cb8cc7f1836fe7778a3", "contracts/agents-api/runtime-observability-api.md": "cd46e777fe716a7e76374f4655c96dfbad9d8be1bfca6203ed6118ab87874c2b", "docs/getting-started/operations.md": "4069e89deed7ef619f28cc8d9779055669246eabe322089113ac3a786c3cb2d5", "docs/user-guide.md": "190bea5bfe23b71db3d9437065ee270e07226a89a6e98c668853e5c7f7555529", @@ -29,18 +34,22 @@ "docs/runtime-bootstrap.md": "0d49aed73b298039e04453e6f465b0e925fb2227fa35d4206820bb3acbd8df39", "docs/runtime-protocol.md": "e8aa4cf862b5f63a4138cfeb25196a6bdb5c40a2e389e828b464585415dc6c45", "docs/sandbox-provider.md": "4d47b234a457f874f3ff7e61a7f5da6fc8b75b0c6df0ce0ce9ead1c07afdfb3e", - "apps/docs/scripts/guides.json": "3c3768fb94fd3d42464d4ce8c55724b9ba8360133c7cc19d513d8ec83a8e034f" + "apps/docs/scripts/guides.json": "d85716ba38429a9f469b1bc1e972f33ed836e277f17636415fbfbb7d8b8a6ce5" }, "outputs": { - "content/docs/index.mdx": "432dd8f02f72edb9f39b92d272719b146c5c1bf5b0429191d0f4a56932b92353", + "content/docs/index.mdx": "5b31a67f14bd01c38321934e4d5ac941de190cb7a61c154feb218f3b0b201b1f", "content/docs/concepts.mdx": "88ba65e1ba902921d6cd5da2866620a6dbef52c041db991312a138884fb43a4e", - "content/docs/execution-model.mdx": "50133f3911c5ad801868e695ad52651e83809b80cbc887ee0bca25769ad32065", + "public/images/source/docs/assets/architecture-overview.png": "c6103e2a8730796a15d6c4ae7165f3b9e60dbd09075b459d34821a3ee0d2d49f", + "public/images/source/docs/assets/architecture-api-surfaces.png": "37c0d0d4f42c37ec41f8d4931ef10f182287d94d0928da195bf8b9e377c942e5", + "public/images/source/docs/assets/architecture-session-flow.png": "0f0a78c43d3dfd235f3994421708c65347863665278bd39e79d19b52e13fab7a", + "content/docs/architecture.mdx": "2c06f4fce7bafdae0e0c2acbc587ab3ece38e473019cef6222f7168fe2429c30", "content/docs/install.mdx": "6c3ec01d1b80cbce35d58e3f141b0fa832d6294a2ecc07c3b286ecc56ba66919", "content/docs/install-options.mdx": "aaafc209293a905d5b433511149aa1f0cc422bd31d5bb5b6cd7eec0d532ab8eb", "content/docs/configure.mdx": "02d1eee789646fdf65ed2ec48b6fe954c81107d6ff5891536ec6ac2df0a8c4dc", "content/docs/bootstrap-projects-keys.mdx": "91a6f62cbe41737adfce9e8ec56e6dc3e2fb0ec8f6b677576f941cdfb378dc47", "content/docs/quickstart.mdx": "d0ab9537ab68f6dd3109353e937a29c5d58ec3894b56a52873c9a1d79dfa60a6", - "content/docs/public-api.mdx": "cd59f4a661f897d1a9dc6ff08a09f7b7504c355288bbf022eff9b70500a9865c", + "content/docs/public-api.mdx": "d5a218219d79f3875a02702257e361b866a5137393b2b8f39aca4be4763be87d", + "content/docs/request-conventions.mdx": "c47b1c5a0785ec786e3d5619218a04a6841538ceefee891ce6e18d2c61a09858", "content/docs/agents-and-tools.mdx": "44dfde4e3b3906b30323c2e75a89650ae4837210c7ba425be2266edf87ce8ff8", "content/docs/sessions.mdx": "bb63d799ed90038836d652f3f866d0309822425114c6b2aa36654b8a991947f6", "content/docs/examples.mdx": "587061e65ab2e841d14980539ba94e2216d4e8135c948a852b9a8bb0359c85d7", @@ -49,13 +58,14 @@ "content/docs/self-hosted-execution.mdx": "eeed4c6b3646927ccc3c7ac2d20b2c0f9c8a65e42d734310fe3959e016324e57", "content/docs/self-hosted-native.mdx": "671451580dfb4f5c134221991f68292a4f992008174d23190b1da3742046571f", "public/images/source/apps/web/public/onboarding/monitor-en.webp": "29dc220cb1250c7016b7c4bf7f30e9510b07c07b814a48c3aa9303b2d76f20b2", - "content/docs/console.mdx": "a930ce36035de74f0c2bef71bed067fc2287ba1c70a485758bf100d484f6adfd", + "content/docs/console.mdx": "a942877466f672fcad297568800ee297f3c969ead0d87d22bc2d5039829241c5", "content/docs/admin-api.mdx": "f43f4f1cac887bc4baa4968d76542a87ba1a6ddeef9259299b53cd98a4aea5e1", + "content/docs/error-codes.mdx": "192e3c4a960fa8a3ce3b2e35bf68eeadad14a598ef007fa00a685a3235291605", "content/docs/observability.mdx": "c81214e1865517a9163c48c7ce7c396f5490c9d162080dfa05fa5ebc147f6c8b", "content/docs/troubleshooting.mdx": "bccd725d2389a80b66caf1a1da80532bd68dd3d470bf851799d0114f84e0af25", "content/docs/user-guide.mdx": "7c099b2d787ce3d7876889c7cefd621840ec083f267eadf278214a83f11ba274", "public/images/source/docs/assets/development-architecture.png": "24e6d0145d4f16ad70b07b6bc643808a6455aaf6398434d199cf74def200fca6", - "content/docs/development.mdx": "2e5249ddfca571d264e93fd1e0e390a4bd5b0b623bda100cd02f2982929850bb", + "content/docs/development.mdx": "3a53e2a8d4c91897e160ce01f07f1609fa101b254bdfa1b0e53ac21f108db342", "content/docs/harness-onboarding.mdx": "17626e9f6256ddfffc95fd81dfa8d9c712d9ff16792ea5ef54bfe8c3ce1a2a9f", "content/docs/runtime-bootstrap.mdx": "58982955811c9ad46a9fc04d8d2aef5a762fc9d25d5833f88aa75ee3fc46523f", "content/docs/runtime-protocol.mdx": "d6b818edf2a0e0c4f2d3878f75805043c6dba3b09c6563f80faa4cecd05d40c7", diff --git a/apps/docs/openapi/core-api.yaml b/apps/docs/openapi/core-api.yaml index 94179a5b2..e6c8c26ab 100644 --- a/apps/docs/openapi/core-api.yaml +++ b/apps/docs/openapi/core-api.yaml @@ -260,7 +260,7 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ModelConfigurationInput' - description: Complete model provider bundle + description: Complete model configuration required: true /core/v1/installation: get: @@ -413,6 +413,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -471,6 +477,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -968,6 +980,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -1075,6 +1093,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Get a self_hosted Session's installation commands @@ -1371,6 +1395,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -2349,6 +2379,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '503': description: Service Unavailable content: @@ -2624,8 +2660,8 @@ paths: - schema: type: integer maximum: 100 - minimum: 0 - description: Page size; 0 returns an empty page + minimum: 1 + description: Page size, 1–100 in: query name: limit - schema: @@ -2649,6 +2685,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillList' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: List Skills in a Project @@ -2677,6 +2743,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillDeleted' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Delete a Skill and its versions in a Project @@ -2704,6 +2800,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.Skill' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Retrieve Skill metadata in a Project @@ -2733,6 +2859,36 @@ paths: schema: type: string format: binary + '400': + description: Bad Request + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Download Skill content in a Project @@ -2756,8 +2912,8 @@ paths: - schema: type: integer maximum: 100 - minimum: 0 - description: Page size; 0 returns an empty page + minimum: 1 + description: Page size, 1–100 in: query name: limit - schema: @@ -2781,6 +2937,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersionList' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: List Skill versions in a Project @@ -2815,6 +3001,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersionDeleted' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Delete a Skill version in a Project @@ -2848,6 +3064,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersion' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Retrieve Skill version metadata in a Project @@ -2883,6 +3129,36 @@ paths: schema: type: string format: binary + '400': + description: Bad Request + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '401': + description: Unauthorized + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '404': + description: Not Found + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '503': + description: Service Unavailable + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Download immutable Skill version content in a Project @@ -3451,6 +3727,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -3502,6 +3784,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -3605,6 +3893,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -3651,6 +3945,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '503': description: Service Unavailable content: @@ -3698,6 +3998,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '503': description: Service Unavailable content: @@ -3750,6 +4056,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: @@ -3983,6 +4295,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '500': description: Internal Server Error content: diff --git a/apps/docs/openapi/public-api.yaml b/apps/docs/openapi/public-api.yaml index 9f8111cc0..f31b6459a 100644 --- a/apps/docs/openapi/public-api.yaml +++ b/apps/docs/openapi/public-api.yaml @@ -68,6 +68,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List reusable Agents @@ -113,6 +119,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Create a reusable Agent @@ -178,6 +190,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a reusable Agent @@ -229,6 +247,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve a reusable Agent @@ -286,6 +310,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Update a reusable Agent @@ -345,6 +375,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an execution Environment @@ -569,6 +605,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List Environment Templates @@ -614,6 +656,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Create an Environment Template @@ -673,6 +721,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete an Environment Template @@ -724,6 +778,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an Environment Template @@ -781,6 +841,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Update an Environment Template @@ -858,6 +924,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List execution Sessions @@ -1021,6 +1093,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete an execution Session @@ -1072,6 +1150,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an execution Session @@ -1129,6 +1213,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Update execution Session metadata @@ -1618,6 +1708,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List persisted execution Items @@ -2158,6 +2254,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List execution Turns @@ -2216,6 +2318,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an execution Turn @@ -2531,6 +2639,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillList' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List Skills @@ -2545,6 +2683,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.Skill' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Upload a Skill @@ -2578,6 +2746,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillDeleted' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Skill and its versions @@ -2599,6 +2797,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.Skill' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve Skill metadata @@ -2620,6 +2848,42 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.Skill' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Update the default Skill version @@ -2650,6 +2914,36 @@ paths: schema: type: string format: binary + '400': + description: Bad Request + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Download Skill content @@ -2692,6 +2986,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersionList' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List Skill versions @@ -2712,6 +3036,42 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersion' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Upload an immutable Skill version @@ -2754,6 +3114,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersionDeleted' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Skill version @@ -2780,6 +3170,36 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.SkillVersion' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve Skill version metadata @@ -2808,6 +3228,36 @@ paths: schema: type: string format: binary + '400': + description: Bad Request + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '401': + description: Unauthorized + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '404': + description: Not Found + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '500': + description: Internal Server Error + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Download immutable Skill version content @@ -2892,6 +3342,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List Vaults @@ -2937,6 +3393,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Create a Vault @@ -3002,6 +3464,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Vault and all its Credentials @@ -3053,6 +3521,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve a Vault @@ -3143,6 +3617,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: List safe Vault Credential metadata @@ -3277,6 +3757,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Vault Credential @@ -3334,6 +3820,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '503': + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve safe Vault Credential metadata diff --git a/apps/docs/openapi/runtime-api.yaml b/apps/docs/openapi/runtime-api.yaml index 18835818d..a5fad6961 100644 --- a/apps/docs/openapi/runtime-api.yaml +++ b/apps/docs/openapi/runtime-api.yaml @@ -30,6 +30,12 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '503': description: Service Unavailable content: @@ -63,6 +69,18 @@ paths: application/json: schema: $ref: '#/components/schemas/api.CoreErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/api.CoreErrorResponse' '503': description: Service Unavailable content: @@ -169,6 +187,12 @@ paths: application/json: schema: $ref: '#/components/schemas/v1.ErrorResponse' + '413': + description: Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/v1.ErrorResponse' '500': description: Internal Server Error content: diff --git a/apps/docs/openapi/sources.json b/apps/docs/openapi/sources.json index e5ba3e4f7..8fd11fd76 100644 --- a/apps/docs/openapi/sources.json +++ b/apps/docs/openapi/sources.json @@ -1,53 +1,226 @@ { "sources": { - "contracts/agents-api/openapi.yaml": "42ae2585b0abe60860de99a6958b639a495a0d9b7c3d0142b199a427fa77b5a5", - "contracts/agents-api/core.openapi.yaml": "f1b9278c3a4b1cb55127cf9471583d00f1ab13b6ceb64f8693a01c4cf03674eb", - "contracts/agents-api/runtime.openapi.yaml": "505286d5eacf94a14f9527fcf4e7beb4fba4f792681be26ba966254cbf49b4aa" + "contracts/agents-api/openapi.yaml": "949acc918b75ceaf9daa102f69e039a42a090eca55b1e521988400d432b2c0d3", + "contracts/agents-api/core.openapi.yaml": "2a351d8e305097853e5404484a8c0b8e9545eb17d72b42da72025273d5941637", + "contracts/agents-api/runtime.openapi.yaml": "d86fa523c6444b7292c06290800cee35dbc723d84dad5740c1d92776fb4165bc" }, "outputs": { - "content/docs/api-reference/agents.mdx": "1f7697959e9c52c9d24fbe70e116e807f49912b9a27ac638b86782e2f326af44", - "content/docs/api-reference/environments.mdx": "6a9e08a67479a745983c45b9711137617c13fdf7599a64533997b00a26ac7282", - "content/docs/api-reference/environment-templates.mdx": "68df9276e858e525e15bb88af624fc8adee8bcdcc03a788faaff56b560fd038c", - "content/docs/api-reference/sessions.mdx": "68a839427c3ff380644fd79e7876fd8fac7a6792179eb3cb9ed376f5953e6e46", - "content/docs/api-reference/artifacts.mdx": "8df8d008126b49b1df88f28a676c4b237ccffc45a470b35ec30eab2daf1c0f7f", - "content/docs/api-reference/events.mdx": "fa509794f3c208c0cdcdaa68615c26b7e400ea6c892922a4e0a6a833e42fe5dd", - "content/docs/api-reference/items.mdx": "fa4d248ac5623beb3f00a4ebb5a6c4ff477865ebee351e0c543a970a7ec3654d", - "content/docs/api-reference/subagents.mdx": "90e2a1a9129111332e36715de2078ee595590c4c25c7b355962e4185bdeb5388", - "content/docs/api-reference/turns.mdx": "46ee9e43aae4ec85b3ee335939dc1e0a238cfda0fb996c6af4d2831bef3377f1", - "content/docs/api-reference/files.mdx": "531c835c66b194ab8876c7663b79e42f0090e12420ae32fafeda24e3143740f4", - "content/docs/api-reference/skills.mdx": "774ea05a7a8250fe5af5164388b98dafca99d56dc2eae686e8f628acb4e7c10b", - "content/docs/api-reference/vaults.mdx": "d80eade1c2f8100030866abbb0fb6b7a09c94250a859c97cdf1abce32fdfdf1e", - "content/docs/api-reference/credentials.mdx": "f129a51f74a3c7021c016600518e2350023f8d29571666ac5d64b7584cd7c7d0", - "openapi/public-api.yaml": "3cdee54523822cd19766771dae4c13a64d6e318ca8e9d5fabe8339e975c8ac25", - "content/docs/api-reference/meta.json": "56bf1dc145ccc8adde38c5f956f1a06f18ef18b646122250d01a294c516f8f83", - "content/docs/api-reference/index.mdx": "9fd6b1c54149874d2999235067c101326f9e8a2e707a70b6672c81eb3ebfe63f", - "content/docs/api-reference/core/core-administration.mdx": "5fc3ada51d2190a141f13738151e4d513390cc3bd66ce6f5013994bda68569b0", - "content/docs/api-reference/core/deployment-model-providers.mdx": "fb15ed2075e256a3fe0222641f95c48c962563325668817ac7cb2a940d9b125d", - "content/docs/api-reference/core/administrator-projects.mdx": "8fd687bb2a7119fa16e938d7c71710c2816afb9cf959eb6849ef5e6300c5419b", - "content/docs/api-reference/core/agents.mdx": "b6c089fbea4b07bc4249e7c7ca5699d47f1512a4fc2d8ee01cb26910ae541a84", - "content/docs/api-reference/core/environment-templates.mdx": "05907f35d7f02d66af9da8b1efaa3765badb4cdf7b94d0f6c3ab0413a2cfa1a9", - "content/docs/api-reference/core/executor-credentials.mdx": "352dc9cb02cceab6a7fa4fe13356e9532c329277224e7e01d18ae0c02cad1a3e", - "content/docs/api-reference/core/native-installation.mdx": "4399eb6c36a221c9459d6773b0bd3b49ce92df120fbca86f99377bcbb1f77811", - "content/docs/api-reference/core/files.mdx": "05ce1d2296dbb3fc76cf4cf98d24dff249114c73529335214cee97363229f384", - "content/docs/api-reference/core/write-audit.mdx": "1298590ab7037077e56f6ab8adb020277763f7a670be796d24142323b2f95411", - "content/docs/api-reference/core/sessions.mdx": "52db14e7c88cb0521a12a9b3d19b14dd38583b97e716b261a44b2bd6bf05140a", - "content/docs/api-reference/core/artifacts.mdx": "620fe72cd41d19b9694fe7080eb8935ef44292852400c7be1c03a893613ca89c", - "content/docs/api-reference/core/execution-configuration.mdx": "f6a9ed4cdb73e87f5f4ce16b4f6fa14b756d07c97f2741bd5cade34a3472c548", - "content/docs/api-reference/core/items.mdx": "7c7b006536d155d003097a504e9931e3dc4d9fd0426852573244453634729250", - "content/docs/api-reference/core/runtime-history.mdx": "eec6384c6fd5a2bf223ec7dc7ee19332440936e18fc67f782fe81b96e299f634", - "content/docs/api-reference/core/runtime-observations.mdx": "db3a238ba77d1fcb887835d51b6f3f8f2b6bdf9cc5e14ac6dd11074a1c75ed48", - "content/docs/api-reference/core/turns.mdx": "53f9472de3e0958c06db7e69d7e8f10119e6540b7f05683915248e08d5284b16", - "content/docs/api-reference/core/skills.mdx": "ed899ade7b032b1732b3097d81419a8fdbb9ead0594fca9f2107da644b97031f", - "content/docs/api-reference/core/vaults.mdx": "12d0aac96cd4a3472ef4eaa287f7945f78862017956e79bfc3ed0ef8e772e78a", - "content/docs/api-reference/core/credentials.mdx": "27d586b9a8fd738b9947802f32c80458195370252886bc26abedccf2125ee981", - "content/docs/api-reference/core/sandbox-manager.mdx": "45e65afffb25e5b6ee2ab0853d7a84dee164e0d44ea384675fbd7ffcbd6c1a58", - "openapi/core-api.yaml": "dc8e80ada4ef8bd93635cab2c5d337b9d7661991a6baa1f69dc4258ebe434ef9", - "content/docs/api-reference/core/meta.json": "d0aef1f54c4cfc30b4e1d974119ae1cdce1c87d5ecba723afbeb4599119482a7", - "content/docs/api-reference/core/index.mdx": "57cf9ea947ef45e79575c25a0a3d4e5e856dde6d14698ccc2c51b86201c249e9", - "content/docs/api-reference/machine/native-installation.mdx": "421a858685b79fdcf8d7eff308c5768d1b62385c3988c6089f380afe80aaed69", - "content/docs/api-reference/machine/sandbox-node.mdx": "5b367a08d43cea82686345d2ba1c75cc90627a7b2970fe42a0df9d77fb3e1e80", - "openapi/runtime-api.yaml": "00be7da2088c0660ec27e656063a0b74eafe97716426ce6aec756e9e942986e8", - "content/docs/api-reference/machine/meta.json": "aa7e1045fb250535d77cdf54b4d2de12a1403e12439e74ce0e16890aadcd93dc", - "content/docs/api-reference/machine/index.mdx": "335881803f4603a759ab88085e8c46754d6b2450da9b1d9338a87968af5871a2" + "content/docs/api-reference/agents/list-reusable-agents.mdx": "7088580883b9c0cb1b010459fe63b30d6a1bc454e541873d3892b381e95fe03b", + "content/docs/api-reference/agents/create-a-reusable-agent.mdx": "ae47d91ea3740c2cd4b3d66e5af57c8229b1bb9c2862522f14f00472e678d315", + "content/docs/api-reference/agents/retrieve-a-reusable-agent.mdx": "3e80c8726b91b6728b8dc5b69e05ab5ccf02ac0ec4f6a5bba57bd8cf2fc848d4", + "content/docs/api-reference/agents/update-a-reusable-agent.mdx": "a01a16c30fab72ce70e7e3afe03e872f92a571ebd7cdad8b327b44ea30ded6a7", + "content/docs/api-reference/agents/delete-a-reusable-agent.mdx": "e4b450ecd9252e0fbe9136bd3513fe4b4aa8b2fb7231f43bf316cd64486693c8", + "content/docs/api-reference/environments/retrieve-an-execution-environment.mdx": "faff964554b886027e40295a6faa8dd3606201083b1f2c0ba76fc9ba121a35c9", + "content/docs/api-reference/environments/list-live-environment-files.mdx": "eda89a737d5c099eb3f04025b76a3ece49e9bf318910860808455ba19c1f2c97", + "content/docs/api-reference/environments/create-an-environment-file-from-inline-bytes-or-a-source-file.mdx": "7e2d083779c52478096eb53c9cac760463fd8577502d042c70bc673dda33eda8", + "content/docs/api-reference/environment-templates/list-environment-templates.mdx": "200027af50cfae5c6a2b39bdde4e75b33513c3fe88d07310fa5bd243039ff08b", + "content/docs/api-reference/environment-templates/create-an-environment-template.mdx": "58761a1881f4d435b9dbdc2e2f41634c6b95fe287b8a76f40845f52ba2485e63", + "content/docs/api-reference/environment-templates/retrieve-an-environment-template.mdx": "146532b416c09fae087a1439244e38f29409da4bee4b354f2d3198fd88598b3c", + "content/docs/api-reference/environment-templates/update-an-environment-template.mdx": "4b1ea639682fdce2bce063cea68cf2928fff646d59235a5d4e17c657193fa7d9", + "content/docs/api-reference/environment-templates/delete-an-environment-template.mdx": "c6f10446d1ca50e0a490c0296aca5d01f39c8ce96423732a271f729575dc278c", + "content/docs/api-reference/sessions/list-execution-sessions.mdx": "fbd004c1385d827feb7c4d9398c3b91297b10c42588186b6e7125b5a38e09b0b", + "content/docs/api-reference/sessions/create-an-execution-session.mdx": "472beea09aa889ecf66701dd97b9c39be4726f4dc7a7ab471658b5c5e3036910", + "content/docs/api-reference/sessions/retrieve-an-execution-session.mdx": "538ec687302c904eb47f6fc00f760a5f6964782d835ab4262ebc531b27c75161", + "content/docs/api-reference/sessions/update-execution-session-metadata.mdx": "f3ad7c0fa0bdb9c6e2afb9382aaa0370fd523a7363904416d12ecebf1e3c8e86", + "content/docs/api-reference/sessions/delete-an-execution-session.mdx": "51afc3a526d6f457df3690119e6771dafcf420850a067ba9a420c712bef85aa3", + "content/docs/api-reference/artifacts/list-immutable-session-artifacts.mdx": "3d586e17f19e24844712bee7aa0515d3fe3e6c9b3452927b3a07953771b94fb9", + "content/docs/api-reference/artifacts/retrieve-immutable-artifact-metadata.mdx": "3bbd8a04508bd0e557f99fda389d19d29f2dd5eddb325f5dc7f5876b2fb79a03", + "content/docs/api-reference/artifacts/delete-a-published-artifact.mdx": "7f45066a7d4ca2db500625a22f14116bd1ef8a77fb15fbecf51a45ce4b6dcee8", + "content/docs/api-reference/artifacts/download-immutable-artifact-bytes.mdx": "e5f842289d785399eb2e6b43a3740f34a170cd771574e2eadc02bde57a0607b7", + "content/docs/api-reference/events/stream-live-session-events.mdx": "dfb350eda50b6349a15394359de6f95e534d43b2f521da070836d0fae23ed013", + "content/docs/api-reference/sessions/submit-session-input-events.mdx": "e517a517e06778a55058347952c593fee7a1e2dd4fd1f75078b03e79a3a3da41", + "content/docs/api-reference/items/list-persisted-execution-items.mdx": "a94e0c89918ec26d5964e731abf06f9ed7ad58168757df5660975855e63f8ec0", + "content/docs/api-reference/subagents/list-session-subagents.mdx": "bed7a780c8b4e75f2cb32b56fb95d502c4ba02ad8646dc4748c0f1bd5fb4943f", + "content/docs/api-reference/subagents/retrieve-a-session-subagent.mdx": "a203ebd474073bb78b249a52a4cf9c3359725e4a6b8580db41f488fd0daec7d0", + "content/docs/api-reference/subagents/list-a-subagent-s-items.mdx": "02f4ed5cb16ca85536909ce14eee2d2eccfc0740366497cb59db76f1394663d4", + "content/docs/api-reference/subagents/list-a-subagent-s-turns.mdx": "87e788c70ac3641827b5c7fd77d55dc33aad0cf14f21b8610377f764964a4261", + "content/docs/api-reference/subagents/retrieve-a-subagent-turn.mdx": "bd1c1ec67c42af99763e10f1d3d2934fc552a5425d23952116182d9d275a9268", + "content/docs/api-reference/subagents/list-a-subagent-turn-s-items.mdx": "0b135b5740efa2eb7426786b272cb029ffcbf075e4f1b73179d49d2d94dc131e", + "content/docs/api-reference/turns/list-execution-turns.mdx": "999a793dce64a548a4d135103a5f14017dc847c8cce3a984dd1a0444e0917e56", + "content/docs/api-reference/turns/retrieve-an-execution-turn.mdx": "79d8954705d11926a24423bbcd227b123cd4b5668ee21cd2c7554b2f7501b071", + "content/docs/api-reference/files/list-source-files.mdx": "a9928c05c70ff7202c69bab3b11fc047aa04520784fa1c41c8e47566fcd66591", + "content/docs/api-reference/files/upload-a-source-file.mdx": "2e8d8e4210f6f209927ce05f6aa2e785a85d151ea23f3a59c9f2ba664ad6b2cf", + "content/docs/api-reference/files/retrieve-source-file-metadata.mdx": "1325fbf3250d93ff76c414922a217de131433fe0c53bf4418cd357cf5cdf5084", + "content/docs/api-reference/files/delete-a-source-file.mdx": "9df0b10380b32baf8e9ffb3ee3ef28480f87090e83f9d828cb68f71ceb287f71", + "content/docs/api-reference/files/download-source-file-bytes.mdx": "cbd88af502663e0156d06d72ac9556b8659ac158b22c62336310cd3e01450c01", + "content/docs/api-reference/skills/list-skills.mdx": "949fc0878718db896b51ffbf532503d6eb438805e404ec07b63d2e66bc713da5", + "content/docs/api-reference/skills/upload-a-skill.mdx": "856e6f4bacb63695bf2ea39df4065f06d20a766f238387b82e4e0e170cc23e74", + "content/docs/api-reference/skills/retrieve-skill-metadata.mdx": "7800ad04ef8d1d9d8440e7f7ad8935bce9f7eb2aad0e37a30f00bfac5535cd7a", + "content/docs/api-reference/skills/update-the-default-skill-version.mdx": "155cd416b020eacbaf58e57f7e65bb1aef51d781aa741704af4530a9c7c6533a", + "content/docs/api-reference/skills/delete-a-skill-and-its-versions.mdx": "f575472b8c5ef0bd0478b1ba487c3a6b513f1f46a327894c853abda02c3496b9", + "content/docs/api-reference/skills/download-skill-content.mdx": "f88343647df91f1d61d84dd6936e2965c7184858336ea24098f5e810812fbcf9", + "content/docs/api-reference/skills/list-skill-versions.mdx": "a5a9e1ac821229f091c09974213adbea86704745da2d8230212bf65657b37a09", + "content/docs/api-reference/skills/upload-an-immutable-skill-version.mdx": "f3175fc7daa600f8ff631cad2901d4cf77d8614a6b190d7259a1d66c555f6dbf", + "content/docs/api-reference/skills/retrieve-skill-version-metadata.mdx": "c31a6cc117e2241fc0cb374e2ba9012702ed7913de6bb50fb928392881583121", + "content/docs/api-reference/skills/delete-a-skill-version.mdx": "ae04aace77dfd22e8f78cd00c854dd166868f1271311f34ce917e8379737e222", + "content/docs/api-reference/skills/download-immutable-skill-version-content.mdx": "3a99d20833a4260256122c21ae422e9704670c249e0db382272a4de00fcec298", + "content/docs/api-reference/vaults/list-vaults.mdx": "940b525048730c26cca42c1d2c1def11153e14560a5e3f1ea8296aff2580cb5a", + "content/docs/api-reference/vaults/create-a-vault.mdx": "ea89b1d5db6c43e1634a9d96cad5b5a746e28f0502799c86b5c7692c21909cc3", + "content/docs/api-reference/vaults/retrieve-a-vault.mdx": "41f6a66ed3d67e908bbb62df2b3b198dba49b52402c44b27f8e3c3057df39c1c", + "content/docs/api-reference/vaults/delete-a-vault-and-all-its-credentials.mdx": "223b9f22a7667d2048ae4053f0786b34f68b07f2433654f277b60b8f2141a4f1", + "content/docs/api-reference/credentials/list-safe-vault-credential-metadata.mdx": "a5c6111261defed35c369fd843eeaaa7f66f7b19a83c1d991237fc9ab506a5a4", + "content/docs/api-reference/credentials/create-a-vault-credential.mdx": "1a2125f543f33f65eee95dd3d7c6c71d63cf2bf9cafbf7d279434ff56cd1d340", + "content/docs/api-reference/credentials/retrieve-safe-vault-credential-metadata.mdx": "26422a11f99cbf28e9c2726c25f9e53bbc37e4d9f629afb88bbe7250ed9a8d42", + "content/docs/api-reference/credentials/replace-vault-credential-authentication-secrets.mdx": "148ac1190942da3e966cbcd2b3d8a5e7751f9f0cc732520a7026b17e216cb3a6", + "content/docs/api-reference/credentials/delete-a-vault-credential.mdx": "e4c6d9673fdc956e017a086496f63ae555afc4db0993f5c817cdc1bb31f6f9d0", + "content/docs/api-reference/agents/index.mdx": "ba75fecd1f307bc18d193cfe11ce839275cdf26535317e1e5db52b5ba43cbc44", + "content/docs/api-reference/agents/meta.json": "2ddb2be361a2ab20777e1dceb0587626496ab2a1183bcc07b2a960c61ba13215", + "content/docs/api-reference/environments/index.mdx": "39dd4d122a40ff25f33313c2e5af18f777a1efb52cae8985a31cfb825f4b4baa", + "content/docs/api-reference/environments/meta.json": "f7146efe4d037368088a0dd457f8083f8916aa6068fe3b6551c8354dff9dbb2a", + "content/docs/api-reference/environment-templates/index.mdx": "c9e4a8444966cad4904114e91259519c05cd78d9f15d6d47bd80a636d56ac570", + "content/docs/api-reference/environment-templates/meta.json": "7e654f6d3579d0acc7bca8346d208d062ba6edb6a2e4516f34caa4e586a400db", + "content/docs/api-reference/sessions/index.mdx": "065928161cda6cada14ed8f31c10fe35a0a1533654ef7d67acbfc96bc5e82c24", + "content/docs/api-reference/sessions/meta.json": "396d8ca196ef13796b3a3a348ed1d26c2cb426cff2ce081e7789d5a2ed61d507", + "content/docs/api-reference/artifacts/index.mdx": "813b5b893b53215e066cb0c4217215338db4697b58598182f0cdde084164a812", + "content/docs/api-reference/artifacts/meta.json": "e6d319d32e5d220489961fa04ad396bb0682c20e1dc1a3a78be2612cf0f258ba", + "content/docs/api-reference/events/index.mdx": "7d888f6482e454f0b635d7dc1dcca1c8999cab454eabc8fdaf5810a540ca2a48", + "content/docs/api-reference/events/meta.json": "83e461ec66ed11c32f91093e4e0441cf9c13890c8eab9ea0914754d345187e88", + "content/docs/api-reference/items/index.mdx": "68e3d8c5f91c14af9a8cb0df710bc77b1f9621105e2e11012e6ee7b28924c756", + "content/docs/api-reference/items/meta.json": "b6771959fd8245eebd4f709a25497a73761b9bb4f0007f846c05fcbf3c3d3694", + "content/docs/api-reference/subagents/index.mdx": "7ba58cd5f54152effb1b68056d00f90fbe385c3f848c36d7393fa582e3c0b143", + "content/docs/api-reference/subagents/meta.json": "b0eda839cbd12c09f7269936b48c18407a9179807ec0c3b03572ae071ff1957f", + "content/docs/api-reference/turns/index.mdx": "dbd5ff0b9936a7c659d20066666aee449065942b6f68fbbab542653b57147d7d", + "content/docs/api-reference/turns/meta.json": "3907409967b3bf58d7d98a5f5228bb2094563b602d21db5dde6fc865fa852795", + "content/docs/api-reference/files/index.mdx": "2c55201787c2a8f5f3b281599181cdfaf4c25749a7aa53adbc4ade783dc05658", + "content/docs/api-reference/files/meta.json": "aa5843ddc46be26d2056e6c8e08f1057c0ab6411e7f12e32aeffce26fb87b91e", + "content/docs/api-reference/skills/index.mdx": "2b8a389523151ffbe5b7d2ac56bbc304eed349a01c547983507c0e6e6e47f514", + "content/docs/api-reference/skills/meta.json": "7247dd6590eda42d9f93af3672b07e2fe1a98b70f5fbc728f4cd63e16eda6553", + "content/docs/api-reference/vaults/index.mdx": "2296f2c171c320300ae47950d490946e0537dc777f42375fd44904ebda27291c", + "content/docs/api-reference/vaults/meta.json": "2cc123f3d126020773a12642bbb867bb789e1f311dcd901a61873fa4f4e09cd5", + "content/docs/api-reference/credentials/index.mdx": "e4a08a3907dac0023900b44090f6ad665b508cb620b71a932ca788705dd9a780", + "content/docs/api-reference/credentials/meta.json": "5e3368b7f365590f31c245fb326fe25c8d3ab82ee4e79e03df10ea016e7b3da3", + "content/docs/api-reference/meta.json": "d8d58d48c955a9b161d880805bc3634617566fe3f1780ee170878358412cafe4", + "content/docs/api-reference/index.mdx": "b32be3060e86fefc5f6b32a67353a2621ea2e7cfd88a69fa19caf67e6ab28d00", + "openapi/public-api.yaml": "2715e821e8c35a9580751b00c72fd5dbf7a8d4adc1332ee2be2bccab593b5842", + "content/docs/api-reference/core/core-administration/query-committed-administrator-mutations.mdx": "bab0589c4dd5944b24594eb2cab6e2266075ce77b7e224cf57a63b9c8e0c89af", + "content/docs/api-reference/core/deployment-model-providers/list-harnesses-and-their-deployment-default-model-providers.mdx": "05a4ef8d4d41c97221a805a4184242b32bd25754223984f36552cf44ec0a7332", + "content/docs/api-reference/core/deployment-model-providers/retrieve-a-harness-s-deployment-default-model-provider.mdx": "7a4aeeb7603fd1328b3145dada0a0778cf9929f91b25938399c465de916b87d6", + "content/docs/api-reference/core/deployment-model-providers/remove-a-harness-s-deployment-default-model-provider.mdx": "b97841a689bb5b72628407068c7b21fd38a75e166b064f29197688bc02f60a73", + "content/docs/api-reference/core/deployment-model-providers/replace-a-harness-s-deployment-default-model-provider.mdx": "99441d2e0a4ed78a1d77307bd9aea008945d97ab0309a81bbb04374ea2dc9025", + "content/docs/api-reference/core/core-administration/retrieve-installation-facts-and-process-settings.mdx": "ece8508bb649e402094dbbf1a8ab1ccdf1549f11b495ff12f15f9ea4f9c00db9", + "content/docs/api-reference/core/core-administration/retrieve-core-operational-metrics.mdx": "183a16362287ab903c10869d7648869ab59da9dbb4d34d66092f9401baca006e", + "content/docs/api-reference/core/administrator-projects/list-projects-and-active-key-counts.mdx": "520c6b56eaa1bf4145ee76f638e36b117dfb3375ab55cafa8512d2d76f59ce51", + "content/docs/api-reference/core/administrator-projects/create-an-empty-independent-project.mdx": "e0c2a3365fb3649e143376ecd55d873f28f98eb4d454453721262483d8690a96", + "content/docs/api-reference/core/administrator-projects/rename-a-project.mdx": "3d0465c69c5594658d9865b1a8b537bf0643ffb1ab66415803baab2550c02f49", + "content/docs/api-reference/core/agents/list-reusable-agents-in-a-project.mdx": "caa598d66b189b3a23d205ff336674acd73aaab6083d3e6c341908d6b7c61627", + "content/docs/api-reference/core/agents/retrieve-a-reusable-agent-in-a-project.mdx": "01c0ccc9997e59205813269138faaaaf8b1f6dd6bb9c88334b1137f8e43f6327", + "content/docs/api-reference/core/agents/delete-a-reusable-agent-in-a-project.mdx": "5c422ab853e48f57d40daf0e4c10168a44ff6814cb471b51ea1255a8dc1273e3", + "content/docs/api-reference/core/administrator-projects/archive-a-project-and-revoke-all-its-keys-while-retaining-assets.mdx": "4773be3ad0ef73fffab399a69513fc8481f231a2afdab510834a59d5f933bf5d", + "content/docs/api-reference/core/environment-templates/list-environment-templates-in-a-project.mdx": "f3fce306cc91afbd870e48b1fd5cc1ba81e3a676e8c45f48edefac39b78855a4", + "content/docs/api-reference/core/environment-templates/retrieve-an-environment-template-in-a-project.mdx": "e17f5f71ccb2af707c4d28887800e974512c33c9ef5999d6a27494879d897938", + "content/docs/api-reference/core/environment-templates/delete-an-environment-template-in-a-project.mdx": "c644d843f6b2b267277cd7af86517a363295d8381f62a623ecf4d030e23bf520", + "content/docs/api-reference/core/executor-credentials/list-a-self-hosted-environment-s-executor-credentials.mdx": "30e4317bcf933a8610b7004dea19ddca82fb168abd0c687bda36bbfd2d6f3870", + "content/docs/api-reference/core/executor-credentials/issue-or-explicitly-rotate-a-self-hosted-environment-executor-credential.mdx": "2ae6b0b5dfd335ea17382e7e12295b1114258dac2d2cf4d3ab9d750ebed062bd", + "content/docs/api-reference/core/executor-credentials/revoke-a-self-hosted-environment-executor-credential.mdx": "4bf944aae82e26c8dec50b2db343fd817871eb1408365d45e8e3a5655970e5c8", + "content/docs/api-reference/core/native-installation/get-a-self-hosted-session-s-installation-commands.mdx": "3ab39864a402e89ccf6ffd7bbed4d32a2ef6a741fb6da3662354d85a4da2aa1e", + "content/docs/api-reference/core/files/list-source-files-in-a-project.mdx": "66f506d01fec625a85252cdaf5b18a6bb0aa3f829b43115db4a6518e40532f5d", + "content/docs/api-reference/core/files/retrieve-source-file-metadata-in-a-project.mdx": "60ec69fc6a5a0b94e94cd9ea3a98784433dd7dd9743d01d0c26e3ab20cd4a5a8", + "content/docs/api-reference/core/files/delete-a-source-file-in-a-project.mdx": "3c1bd990656b421c530c65a8588a1bc7550ac1b1ecd8fa6ef6d283e6918fcae8", + "content/docs/api-reference/core/administrator-projects/list-safe-key-metadata-for-a-project.mdx": "8d3d8218225bd9b89e62cf16598409bd6be5f4e16da6f414b7386b6bb5b7aee7", + "content/docs/api-reference/core/administrator-projects/issue-an-independent-secret-in-an-existing-project.mdx": "a9897229218a8ab0ff8ea1398a6e38bfc1582de32065b00ad0e9345c37a8d265", + "content/docs/api-reference/core/administrator-projects/revoke-one-project-key-while-retaining-shared-assets.mdx": "d83bee4021b2613c4286898ecd9c166ca2e8f44af6ffd376fbec482abaf8370f", + "content/docs/api-reference/core/write-audit/batch-lookup-resource-creation-keys.mdx": "764359c2e06f6401a370a1a49f900e28fc3a9a899eaa373b633afb7ec4fb708d", + "content/docs/api-reference/core/sessions/list-execution-sessions-in-a-project.mdx": "62a212d40d375d3c008a476e8496a00471213182159cec631be4d2290f38cd0b", + "content/docs/api-reference/core/sessions/retrieve-an-execution-session-in-a-project.mdx": "eaa87cf0858ccc581d10c084a92c043bb0b642be25c86bd8a8f95d82acb814b1", + "content/docs/api-reference/core/sessions/delete-an-execution-session-in-a-project.mdx": "217f97912fd65d3d2787832532d98ed41237ef6a916b33077a206d598161b961", + "content/docs/api-reference/core/core-administration/retrieve-a-managed-session-s-resource-cleanup-state.mdx": "7ccf1479a9bd847ca8b22d86aea6869847f1e0e8db0aea60fff1bf74c20e4421", + "content/docs/api-reference/core/core-administration/release-a-managed-session-s-execution-resources-while-retaining-history.mdx": "9bfd710a716c1cb998ae7533f9677cfec458db1c9972a242dc3f72553206311c", + "content/docs/api-reference/core/artifacts/list-immutable-session-artifacts-in-a-project.mdx": "dea6f358bc70ee1ed34ed3b8260792d6442b7809c6b279a62726465a6ccb5f02", + "content/docs/api-reference/core/artifacts/retrieve-immutable-artifact-metadata-in-a-project.mdx": "81ee1652348de1ef10719d3236f3d00c98fe5a6b4e213977898ad1a9cb3d3334", + "content/docs/api-reference/core/artifacts/delete-a-published-artifact-in-a-project.mdx": "d52aa4ae83e48de4c12756af06c6923ea5ae89682f758e02a73696906f43cdfc", + "content/docs/api-reference/core/artifacts/download-immutable-artifact-bytes-in-a-project.mdx": "817f6ff7b1159dcb2088bcbb61ccc46132fa56e7cdec89e009a5b2247e89dc0f", + "content/docs/api-reference/core/sessions/retrieve-root-session-diagnostics.mdx": "3d5320afcc3baf5d87e155f56f1004d60396684e257443c03dedede706e27cb0", + "content/docs/api-reference/core/execution-configuration/retrieve-a-session-s-frozen-execution-configuration-in-a-project.mdx": "8c1d75bcc6055a08d7ae2e4c04d4636541fc04763590fdfbaa453e874ffed379", + "content/docs/api-reference/core/items/list-persisted-execution-items-in-a-project.mdx": "b0880a19798c58b23d4449b4b10bd6df1230946b7db7e27fe3761bf7e5135b4c", + "content/docs/api-reference/core/runtime-history/retrieve-session-runtime-history-in-a-project.mdx": "a116e130dbfe9cf3a867071a3438e7b3a8a90dca91c8e71494a4088eccbd2755", + "content/docs/api-reference/core/runtime-observations/retrieve-a-session-runtime-observation-in-a-project.mdx": "eec44212e62f594cdeedc8de9ba578e7e17895e9f7e6c12f5c641d5138eafa60", + "content/docs/api-reference/core/turns/list-execution-turns-in-a-project.mdx": "b04ce4228c0831a38728a2142da728604191ccf9e52e63848fda3a99c32cad57", + "content/docs/api-reference/core/turns/retrieve-an-execution-turn-in-a-project.mdx": "e2b15095ab033cd24ee5db17cbc65c7b552cbcaf26574eb54bec9b87dd2aa50d", + "content/docs/api-reference/core/turns/retrieve-root-turn-diagnostics.mdx": "c9150f082128cadf9cb88b48f34794acfda64305f8c51d6ed3d87de423d1dffb", + "content/docs/api-reference/core/skills/list-skills-in-a-project.mdx": "0187c18ddab336ccffb170d6307198c0d3f51c89356910ef8a4eb3aa98007a03", + "content/docs/api-reference/core/skills/retrieve-skill-metadata-in-a-project.mdx": "e3fb7136d3066b1263a2d237e2374ae50bda4b001d3bc95fbaadc2078afa3951", + "content/docs/api-reference/core/skills/delete-a-skill-and-its-versions-in-a-project.mdx": "11cf37d2e8ba426de8f666d721a5c9f5928e0767a7b91f601af5a409a9b30f38", + "content/docs/api-reference/core/skills/download-skill-content-in-a-project.mdx": "c34dbd6c95b72a4e6c687f52af95e2111e9ab9984f1cc9d24709e476e51c8e4d", + "content/docs/api-reference/core/skills/list-skill-versions-in-a-project.mdx": "7cbd5bdebc2daacf431d7d81bb8648b4ed039fb4755ee07b829e41cf1824d5c9", + "content/docs/api-reference/core/skills/retrieve-skill-version-metadata-in-a-project.mdx": "b7fd7dfaee3a7bce2c224be1b2db07cf7dc37ca40d48205c93d7ce257c9b6866", + "content/docs/api-reference/core/skills/delete-a-skill-version-in-a-project.mdx": "9c6c0134ae53867d2fba1e9650176806af6a50eeab4c1013f6e5d3a01bf5f722", + "content/docs/api-reference/core/skills/download-immutable-skill-version-content-in-a-project.mdx": "ab97f631cc92affa5465f336b75020bf1c16777f2bc5d6830c3e4e37803bfaf0", + "content/docs/api-reference/core/vaults/list-vaults-in-a-project.mdx": "da26e807ae9c7a0e59d7e12e406b7b8e57e4d766685ec6698e5da031ebb43639", + "content/docs/api-reference/core/vaults/retrieve-a-vault-in-a-project.mdx": "ad23cdfa3e157deb83de633da42b8fa0c8a6c4e73b19b4598912f5040487797d", + "content/docs/api-reference/core/vaults/delete-a-vault-and-all-its-credentials-in-a-project.mdx": "9120d5145bb6a7203371e43c9403ffbb57421cdd8856546652a93ac3914c825c", + "content/docs/api-reference/core/credentials/list-safe-vault-credential-metadata-in-a-project.mdx": "3eb26152100e40b2001f4ade4528df05f9349bf48071389991420cce74503a36", + "content/docs/api-reference/core/credentials/retrieve-safe-vault-credential-metadata-in-a-project.mdx": "a5c0632b8b6e943ac1f33b8c0e3f7eb9cc80cb739ee049d44817f27f95ed4e6e", + "content/docs/api-reference/core/credentials/delete-a-vault-credential-in-a-project.mdx": "c68abf123cb34a91070a8c5fa061fc5cf00f0ec0e5b1ab6c3fe2a6578fe49416", + "content/docs/api-reference/core/write-audit/query-api-key-write-operations.mdx": "d911082ab5d82d439980a165c1a2ad5afc276975592d2a6641211639d19806b9", + "content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-deployment.mdx": "bdd6d6aacc76943e58c09f7be23ed7c3c3cc5914b79f215c45a55b27fcd6e5ab", + "content/docs/api-reference/core/sandbox-manager/initialize-the-deployment-sandbox-provider.mdx": "39ece85872e2ab283ea6be293cd3e97a39a83bdcb25b0dbf45cf4f78510ec31c", + "content/docs/api-reference/core/sandbox-manager/change-the-sandbox-deployment-configuration.mdx": "4647c631def4ec5b48a736fca7dade8e80857f9af44685c42f96ac09a4337763", + "content/docs/api-reference/core/sandbox-manager/start-or-escalate-a-durable-sandbox-deployment-reset.mdx": "136ce44903b0efef94454e738c8f23f8ca2d2ef3aecb567e9afdec4c2e1ec923", + "content/docs/api-reference/core/sandbox-manager/cancel-a-sandbox-deployment-reset.mdx": "858bb0ea9a0bc5a7840ec8d5b5ed44fe85f930f8045596a0ab1fddefc9ce04b1", + "content/docs/api-reference/core/sandbox-manager/list-templates-visible-to-an-e2b-credential.mdx": "8da8d150b5db59630d426824592cb41bc31f7ee83f5a77dc27934b14717a4977", + "content/docs/api-reference/core/sandbox-manager/list-ready-builds-for-an-e2b-template.mdx": "2b6df60778df1fe40cdb0d7659ce47ba227142b7c484e635672a2a3b7daef001", + "content/docs/api-reference/core/sandbox-manager/create-a-ten-minute-one-use-node-enrollment-token.mdx": "49f4cfe9bbf67cbf51790f82186877802a76c4e18bb36e163a9693d1072704b6", + "content/docs/api-reference/core/sandbox-manager/list-deployment-sandbox-nodes.mdx": "f1cf29d0830b91659401440eab87741bac5984bb0eb95de2f5d5ed11aec78e18", + "content/docs/api-reference/core/sandbox-manager/retrieve-sandbox-node-and-host-history.mdx": "a2bac2f358b3c9926e6eef3f8ffa31e701d0afcb3afe07d43fa1ca4a68320f09", + "content/docs/api-reference/core/sandbox-manager/update-sandbox-node-name-and-capacity.mdx": "03446b3e04907e7771138337720efe7e8165bee423b3c0fbe2c7834fdcba30cf", + "content/docs/api-reference/core/sandbox-manager/remove-a-sandbox-node-with-no-retained-resources.mdx": "c2eae5faff754e2202f995ce6e2ddded98671f6cf1d89298df0996081e4be15d", + "content/docs/api-reference/core/sandbox-manager/list-retained-allocations-on-a-sandbox-node.mdx": "311af4031f237c35804192de31e7d0fa9fda816ea81405e6244f528bd70633c4", + "content/docs/api-reference/core/core-administration/list-runtime-observations-across-managed-projects.mdx": "bf540d3dc5314b87e78df676372576538450e2cfaf9f52dc34acad19cbf513f5", + "content/docs/api-reference/core/core-administration/summarize-resource-counts-and-session-usage-by-project-agent-or-creator-key.mdx": "8fb652245d65e3b4e095faf49af34b7337e43ccb3195d0be4588f571d3b14501", + "content/docs/api-reference/core/core-administration/index.mdx": "88db7e7d59cc6dfed471da887ddff69b29ea17534f9a1f6294c231d653b26ec6", + "content/docs/api-reference/core/core-administration/meta.json": "a169f612d45e3199b45b3b958fa20a389a9fd472583f12fa69f050e9bb834478", + "content/docs/api-reference/core/deployment-model-providers/index.mdx": "54392959ade32ca8f2e1589ac3c5aa72f959b881a3e491f0fd25c731e89f78c1", + "content/docs/api-reference/core/deployment-model-providers/meta.json": "e195e58454f75bc989d571a5339474052e63f8be97b0f38bdcf3e353eaffc87e", + "content/docs/api-reference/core/administrator-projects/index.mdx": "13166281b709e899fcd0856267ed41c4ade308006a2987fdc46fdda8bbb98e98", + "content/docs/api-reference/core/administrator-projects/meta.json": "de60495ce59bc605e78b423e64605ad43dcba3af4a05172afa35f57a63107b53", + "content/docs/api-reference/core/agents/index.mdx": "6517e71facb1398d3b9372e92c2533474c849f5ea6db1a7fe6604428bd549f4a", + "content/docs/api-reference/core/agents/meta.json": "60bc344e4e410f6e136bfca2b98a0e08bfdb0b40cbadb46f6623b784b5f78522", + "content/docs/api-reference/core/environment-templates/index.mdx": "7ba91b3d7aa77e7ef216e692d4787ce15e5fad0f07a3d1e4c8b9dbc2add33c51", + "content/docs/api-reference/core/environment-templates/meta.json": "a60bd3832822f4244f9a6175e4eb794b72c15977241df6910a523265e01037b7", + "content/docs/api-reference/core/executor-credentials/index.mdx": "966bd24d0c491b6f062ca2eff33498028ab8b39e00533ff60647fb97a41a41c3", + "content/docs/api-reference/core/executor-credentials/meta.json": "7456cda60ecbe86562ca5438b9228f516e172e5ce562541640b3158ef7770dc9", + "content/docs/api-reference/core/native-installation/index.mdx": "3da7f4bc6761428aa9650fca00c9e639cb0f83757f4137ff7e496f7c0bad5ba7", + "content/docs/api-reference/core/native-installation/meta.json": "754723b59187015842343b5bdae1347bcee9945401c78bcd898db6d8587f5e9c", + "content/docs/api-reference/core/files/index.mdx": "3a0274fb0beec16190a1f709956aae68bb2d392fceeebae724520a437c55dda0", + "content/docs/api-reference/core/files/meta.json": "4e78b79f585a12d311d23429d56bb36a84e0478482fc4209e022594d1fddd5af", + "content/docs/api-reference/core/write-audit/index.mdx": "cdc02ebdf46223737b52bf50ffc67fc2fdc214a1058253281cd77c0739dc50bb", + "content/docs/api-reference/core/write-audit/meta.json": "4c17b5a06c99c634be9d05916c84486af639deb47f2a3d5eb3153771fe7c7d3f", + "content/docs/api-reference/core/sessions/index.mdx": "89d71bfa7cb78b0ad6236212646c9240ebf259be72cbab129d970c7e6dc220c5", + "content/docs/api-reference/core/sessions/meta.json": "f01061753eb3db2ffe052e9422dfa1b4e709d235cb076833ecbe11b90bdd757f", + "content/docs/api-reference/core/artifacts/index.mdx": "5ef849b7f353b246c5137fb5305a1387b99298ddd777389e02d5cebcf4deb68d", + "content/docs/api-reference/core/artifacts/meta.json": "5156b8a414eb6da113960abe09d30e255e21891820669fdcba49f295a7bcf31c", + "content/docs/api-reference/core/execution-configuration/index.mdx": "fc60df970294ce9ac8e9750888897e5e9fe5f5b525d5d8f3eecbf5bb2f25c5a2", + "content/docs/api-reference/core/execution-configuration/meta.json": "d971206ad0f78bb0f093ae33b8488f6eaf8ef1a04a8e7882f2f3edc9a096c0e3", + "content/docs/api-reference/core/items/index.mdx": "58d86426566aa71263eac72b5704ae4352a9ed237b80576e3dbd653ca52501a1", + "content/docs/api-reference/core/items/meta.json": "c6a1139633e0fe14c323a7bf3d8797e794368065ce5c0761755d621576d71c0d", + "content/docs/api-reference/core/runtime-history/index.mdx": "8898722b8da575d848651f8991d5e6aad0ac4302dbc78d926d964c4a02af915b", + "content/docs/api-reference/core/runtime-history/meta.json": "d24b260c692975497824f328cfb5e2101ac426a149684317778f50645ba01584", + "content/docs/api-reference/core/runtime-observations/index.mdx": "16ca7ff79d12dbe951b2b1fa70554a530580d1c7415475affd7287fa209365de", + "content/docs/api-reference/core/runtime-observations/meta.json": "8907d72be08e84d600eabac93603d6e0c27d1c2e672e1ceff04cd7b856ad1b0c", + "content/docs/api-reference/core/turns/index.mdx": "bc156b3e6ee689be1418977abb1f6f19e4801473d4f4ff09aea862898852ba36", + "content/docs/api-reference/core/turns/meta.json": "40cfaaad239a43ab7de78b0eef7418646a037bb6e5faf978b6d27f92cf714ca3", + "content/docs/api-reference/core/skills/index.mdx": "66a8f52dc19846c779b320d4b254bd717b1df368ab9f0706dc4d489ae888acb1", + "content/docs/api-reference/core/skills/meta.json": "29f1b629fe626cdbf3de7c345cdd0b5821a5ff3363c6cf71c549435a1f9a7cf6", + "content/docs/api-reference/core/vaults/index.mdx": "1b6f1523318a96f178ae7110acc1afe8ec4878a1acb7a773cc7ea941fa463deb", + "content/docs/api-reference/core/vaults/meta.json": "0596db6fdcaebcb360fd9e6f0cb3720b822287cd66aea6fd4798deb9713dacb3", + "content/docs/api-reference/core/credentials/index.mdx": "d6bafc16421923fd5fc5b570677136b3623e84bd431a2c635f0259553d758b46", + "content/docs/api-reference/core/credentials/meta.json": "fe7cedd70a4785dc222748e7d2846e92fccea58dd01d47e2e054df23e83f45ee", + "content/docs/api-reference/core/sandbox-manager/index.mdx": "66b38e9c267134171f4296b41665f93c66ede0c3cfbc512987082b08297850f7", + "content/docs/api-reference/core/sandbox-manager/meta.json": "87c4a3068098b5b4c764a8a75bec5699be5a5edd3231e9dcd991ad197d0a9190", + "content/docs/api-reference/core/meta.json": "5d449afad9a6c3eb73a691a549bb7c2410cd2a2257177dc0cc9008cb42c855c1", + "content/docs/api-reference/core/index.mdx": "abfa13ae8ed90793b018ec3a70e4afdb15bd98dc55fabc56b8b9417283e72e3b", + "openapi/core-api.yaml": "dceafefddca3b2a5d2c61a3b4a82b00b5961fd550eeb4e9d8c637d4e381bd265", + "content/docs/api-reference/machine/native-installation/resolve-a-native-installation-authorization.mdx": "5c9d983c7a97e92d4c541d9ebbdb5e869eb3d52d32870709f979583305ffbd25", + "content/docs/api-reference/machine/native-installation/claim-an-environment-s-installation-credential.mdx": "45223298aa8ec65cdfbe8e2685306ba14c39db898e534fca205e9a658cf7f344", + "content/docs/api-reference/machine/sandbox-node/read-the-active-configuration-for-node-installation.mdx": "7aa907f1b00b82a4d6cc7ba50f11fd19558baf5deddbcf34c0d1e7aecf577efc", + "content/docs/api-reference/machine/sandbox-node/enroll-a-sandbox-node.mdx": "90e7d27beda3286aab3d29d161b6f89158c410f0ad8121449f52b456d22b2601", + "content/docs/api-reference/machine/sandbox-node/recover-an-enrolled-sandbox-node-identity-and-observe-its-readiness.mdx": "ffb74feabb887e0f9a69635acf7213286b56e2aa6d164162c1fc81ddb1bb9624", + "content/docs/api-reference/machine/native-installation/index.mdx": "bf953a4061664ca40d2c66f5335bb756cbe07bc1ebd7882bc8ba52f44f222bf7", + "content/docs/api-reference/machine/native-installation/meta.json": "dc8871ae2e6637eef5b0506eeb1dc582f4b41d019ae7301ad79f3001e8970d81", + "content/docs/api-reference/machine/sandbox-node/index.mdx": "dfecdf0e1f1b7dd9baea4018f8b26b5c688cf7d230f508803aff236ccb236a80", + "content/docs/api-reference/machine/sandbox-node/meta.json": "1e84da2499923fe60e436a53b0983f8926400522ffe3719eede69890b06a329d", + "content/docs/api-reference/machine/meta.json": "8c5c7c9c6a16185475a42ecce327313c0f8662731b307a8d648075038fea6eb0", + "content/docs/api-reference/machine/index.mdx": "c0dcc9631ff6a3736b8ee71274d33c9fce86f91d9ceedf52012db06a41c78069", + "openapi/runtime-api.yaml": "154291666d72eb5b8d844080ce3f7f5f4966b21b89260e66a1e46cefb03e2711" } } diff --git a/apps/docs/package.json b/apps/docs/package.json index d736c306b..15251f1e4 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -8,11 +8,12 @@ "dev": "next dev --port 4000", "build": "fumadocs-mdx && next build && node scripts/verify-prerender.mjs", "api:generate": "node scripts/generate-api-reference.mjs", - "verify": "pnpm verify:contracts && pnpm verify:routes && pnpm verify:copy && pnpm verify:docs && pnpm verify:links", + "verify": "pnpm verify:contracts && pnpm verify:routes && pnpm verify:copy && pnpm verify:docs && pnpm verify:errors && pnpm verify:links", "verify:contracts": "node scripts/verify-contract-freshness.mjs", "verify:routes": "node scripts/check-python.mjs routes", "verify:copy": "node scripts/verify-api-copy.mjs", "verify:docs": "node scripts/verify-docs-facts.mjs", + "verify:errors": "node scripts/verify-error-codes.mjs", "verify:links": "node scripts/verify-links.mjs", "check:prerender": "node scripts/verify-prerender.mjs", "check:site": "node scripts/check-site.mjs", diff --git a/apps/docs/public/images/architecture.svg b/apps/docs/public/images/architecture.svg deleted file mode 100644 index 9f8abb1de..000000000 --- a/apps/docs/public/images/architecture.svg +++ /dev/null @@ -1,10 +0,0 @@ - -OpenAgentCore API and execution boundariesApplications call Core with Project API keys. Administrator browsers sign into Web; Web holds the Core key. Nodes and Runtime daemons connect directly to Core using scoped machine credentials. Core owns execution and its PostgreSQL state. - - - -Application / SDKAdministrator browserWeb serverCoreExecution ownerPostgreSQLNode / Runtime / native harness - -/v1 · Project API keySession/core/v1Core key/api/v1Scoped machine credentials -Application API and administration API are separate. Machine connections never pass through Web. - diff --git a/apps/docs/public/images/source/docs/assets/architecture-api-surfaces.png b/apps/docs/public/images/source/docs/assets/architecture-api-surfaces.png new file mode 100644 index 000000000..a4b997d21 Binary files /dev/null and b/apps/docs/public/images/source/docs/assets/architecture-api-surfaces.png differ diff --git a/apps/docs/public/images/source/docs/assets/architecture-overview.png b/apps/docs/public/images/source/docs/assets/architecture-overview.png new file mode 100644 index 000000000..7d2cccf5d Binary files /dev/null and b/apps/docs/public/images/source/docs/assets/architecture-overview.png differ diff --git a/apps/docs/public/images/source/docs/assets/architecture-session-flow.png b/apps/docs/public/images/source/docs/assets/architecture-session-flow.png new file mode 100644 index 000000000..660755ac8 Binary files /dev/null and b/apps/docs/public/images/source/docs/assets/architecture-session-flow.png differ diff --git a/apps/docs/scripts/check-browser.mjs b/apps/docs/scripts/check-browser.mjs index 8bd3476ff..5de2d9fff 100644 --- a/apps/docs/scripts/check-browser.mjs +++ b/apps/docs/scripts/check-browser.mjs @@ -18,7 +18,17 @@ page.on('pageerror', error => failures.push(error.message)) const screenshots = process.env.DOCS_SCREENSHOT_DIR if (screenshots) fs.mkdirSync(screenshots, { recursive: true }) try { - for (const route of ['/', '/install', '/configure', '/console', '/execution-model', '/api-reference/agents', '/api-reference/core/sandbox-manager', '/api-reference/machine/sandbox-node', '/harness-onboarding']) { + // Tag overviews name the surface credential; operation pages document the + // Authorization header of that operation. + const credentials = { + '/api-reference/agents': 'Project API key', + '/api-reference/core/sandbox-manager': 'Core key', + '/api-reference/machine/sandbox-node': 'enrollment', + '/api-reference/agents/list-reusable-agents': 'Authorization', + '/api-reference/core/sandbox-manager/retrieve-sandbox-deployment': 'Authorization', + '/api-reference/machine/sandbox-node/enroll-a-sandbox-node': 'Authorization', + } + for (const route of ['/', '/install', '/configure', '/console', '/architecture', ...Object.keys(credentials), '/harness-onboarding']) { const response = await page.goto(origin + route, { waitUntil: 'networkidle' }) assert.equal(response.status(), 200, route) assert.ok(await page.locator('h1').count(), 'Missing page title: ' + route) @@ -26,9 +36,9 @@ try { assert.ok((await page.title()).includes('OpenAgentCore Docs'), 'Wrong page metadata: ' + route) if (route.includes('/api-reference/')) { assert.equal(await page.locator('input, form, textarea').count(), 0, 'Reference exposes request controls: ' + route) - assert.ok((await page.locator('body').innerText()).includes('Authorization'), 'Missing credential documentation: ' + route) + assert.ok((await page.locator('body').innerText()).includes(credentials[route]), 'Missing credential documentation: ' + route) } - if (screenshots && ['/', '/console', '/execution-model', '/api-reference/core/sandbox-manager', '/harness-onboarding'].includes(route)) { + if (screenshots && ['/', '/console', '/architecture', '/api-reference/core/sandbox-manager', '/harness-onboarding'].includes(route)) { await page.screenshot({ path: path.join(screenshots, (route.replaceAll('/', '-') || 'home') + '.png'), fullPage: false }) } } @@ -37,7 +47,7 @@ try { assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth + 1), 'Mobile page overflows viewport') assert.deepEqual(failures, [], 'Browser runtime errors') assert.deepEqual(unexpected, [], 'Documentation made external requests') - console.log('Nine desktop routes, developer navigation, mobile layout and read-only API controls passed; no external requests.') + console.log('Twelve desktop routes, developer navigation, mobile layout, API credentials and read-only API controls passed; no external requests.') } finally { await context.close() await browser.close() diff --git a/apps/docs/scripts/check-python.test.mjs b/apps/docs/scripts/check-python.test.mjs index 05d5b6697..dc21cf6ee 100644 --- a/apps/docs/scripts/check-python.test.mjs +++ b/apps/docs/scripts/check-python.test.mjs @@ -22,7 +22,7 @@ test('route gate and Python regressions honor the selected interpreter without s }) assert.equal(result.status, 0, result.stdout + result.stderr) if (mode === 'routes') assert.match(result.stdout, /Contract operations:\s+[1-9]\d*\b/) - else assert.match(result.stderr, /Ran 2 tests/) + else assert.match(result.stderr, /Ran 3 tests/) } const invocations = fs.readFileSync(log, 'utf8').trim().split('\n').map(line => JSON.parse(line)) assert.equal(invocations.length, 2) diff --git a/apps/docs/scripts/contracts.mjs b/apps/docs/scripts/contracts.mjs index e8b6356e3..7fac681b3 100644 --- a/apps/docs/scripts/contracts.mjs +++ b/apps/docs/scripts/contracts.mjs @@ -14,6 +14,82 @@ export const surfaces = [ { id: 'runtime-api', file: 'runtime.openapi.yaml', directory: '/machine', title: 'Machine connection API', prefix: '/api/v1', credential: 'Route-specific node enrollment, node, daemon, or executor credential', authority: 'Generated local machine contract. These connections reach Core directly, never through Web.' }, ] export function sourcePath(surface) { return path.join(repoRoot, 'contracts/agents-api', surface.file) } + +// A contract route as a caller sends it. Core and machine routes already carry +// their namespace; public routes are relative to /v1. +export function fullPath(surface, route) { + return route === surface.prefix || route.startsWith(surface.prefix + '/') ? route : surface.prefix + route +} + +// An operation description is a short lead and optional details. The lead is +// the first paragraph, or for a single paragraph its first sentences up to at +// least 40 characters ("Core key only." alone says too little). +export function splitDescription(text = '') { + const trimmed = text.trim() + const paragraph = trimmed.indexOf('\n\n') + if (paragraph >= 0) return { lead: trimmed.slice(0, paragraph).trim(), details: trimmed.slice(paragraph + 2).trim() } + const sentence = /[.!?](?=\s+[A-Z`"(])/g + let end = -1 + for (let match; (match = sentence.exec(trimmed));) { + end = match.index + 1 + if (end >= 40) break + } + if (end < 0 || end >= trimmed.length - 1) return { lead: trimmed, details: '' } + return { lead: trimmed.slice(0, end), details: trimmed.slice(end).trim() } +} + +// Contract prose is one long paragraph, so a page would open with a wall of +// text that pushes the request section below the fold. The site instead keeps +// the lead under the title and folds the rest into a collapsed block, regrouped +// into short paragraphs. The contract text itself stays verbatim. +export function detailsBlock(details = '') { + const text = details.trim() + if (!text) return '' + const body = mdxText(paragraphise(text)) + // A short remainder reads better in place than behind a summary. + if (text.length <= 400) return body + '\n\n' + return `
\nFull description\n\n${body}\n\n
\n\n` +} + +// Sentence boundaries are the ones splitDescription uses: a terminator followed +// by a new sentence starting with a capital, backtick or quote. Abbreviations +// and paths such as "e.g. the ID" or "/v1.x files" stay in one sentence. +function sentences(text) { + const boundary = /[.!?](?=\s+[A-Z`"(])/g + const found = [] + let start = 0 + for (let match; (match = boundary.exec(text));) { + found.push(text.slice(start, match.index + 1)) + start = match.index + 1 + } + found.push(text.slice(start)) + return found.map(sentence => sentence.trim()).filter(Boolean) +} + +// Prose a contract already laid out as list items, tables or hard-wrapped lines +// is kept exactly as written; only a single long paragraph is regrouped. +function paragraphise(text, per = 3) { + return text.split(/\n{2,}/).map(block => { + const trimmed = block.trim() + if (!trimmed) return '' + if (/[\n|]/.test(trimmed) || /^([-*+]|\d+\.)\s/.test(trimmed)) return trimmed + const parts = sentences(trimmed) + const grouped = [] + for (let i = 0; i < parts.length; i += per) grouped.push(parts.slice(i, i + per).join(' ')) + return grouped.join('\n\n') + }).filter(Boolean).join('\n\n') +} + +// Markdown from a contract, made safe for MDX: braces and angle brackets stay +// literal text outside code spans. +// Page descriptions render as plain text, so the lead drops inline markdown. +export function plainText(text) { + return text.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/\*\*([^*]*)\*\*/g, '$1').replace(/`([^`]*)`/g, '$1') +} + +export function mdxText(text) { + return text.split(/(`+[^`]*`+)/g).map((part, i) => i % 2 ? part : part.replaceAll('{', '{').replaceAll('}', '}').replaceAll('<', '<')).join('') +} export function normalise(surface, source = yaml.load(fs.readFileSync(sourcePath(surface), 'utf8'))) { if (source.swagger !== '2.0' && !/^3\./.test(source.openapi ?? '')) throw new Error('Unsupported contract format: ' + surface.file) const base = source.basePath === '/' ? '' : (source.basePath ?? '') diff --git a/apps/docs/scripts/contracts.test.mjs b/apps/docs/scripts/contracts.test.mjs index bf191d9af..15eb2d83f 100644 --- a/apps/docs/scripts/contracts.test.mjs +++ b/apps/docs/scripts/contracts.test.mjs @@ -6,7 +6,50 @@ import path from 'node:path' import yaml from 'js-yaml' import { createOpenAPI } from 'fumadocs-openapi/server' import { schemaToString } from '../node_modules/fumadocs-openapi/dist/utils/schema-to-string.js' -import { appRoot, normalise, surfaces } from './contracts.mjs' +import { appRoot, normalise, surfaces, splitDescription, detailsBlock, mdxText, plainText, fullPath } from './contracts.mjs' + +test('overview paths carry the namespace a caller sends', () => { + const [publicApi, coreApi] = surfaces + assert.equal(fullPath(publicApi, '/agents/{agent_id}'), '/v1/agents/{agent_id}') + assert.equal(fullPath(coreApi, '/core/v1/sandbox/deployment'), '/core/v1/sandbox/deployment') + assert.equal(fullPath(publicApi, '/v1'), '/v1') +}) + +test('operation descriptions split into a lead and details', () => { + assert.deepEqual(splitDescription('Saves an Agent.\n\n- Limit one.\n- Limit two.'), { lead: 'Saves an Agent.', details: '- Limit one.\n- Limit two.' }) + // A single paragraph splits after the first sentences that reach 40 characters. + assert.deepEqual(splitDescription('Core key only. Returns the harnesses Core supports. Keys are never returned.'), + { lead: 'Core key only. Returns the harnesses Core supports.', details: 'Keys are never returned.' }) + // Abbreviations and paths do not end a sentence; a short description stays whole. + assert.deepEqual(splitDescription('Returns metadata, e.g. the ID, for /v1.x files.'), { lead: 'Returns metadata, e.g. the ID, for /v1.x files.', details: '' }) + assert.deepEqual(splitDescription(undefined), { lead: '', details: '' }) +}) + +test('a long description folds into paragraphs that keep every sentence', () => { + const text = Array.from({ length: 12 }, (_, i) => `Fact number ${i + 1} is stated in this description.`).join(' ') + assert.ok(text.length > 400, 'the fixture must be long enough to fold') + const block = detailsBlock(text) + assert.match(block, /^
\nFull description<\/summary>\n\n/) + assert.match(block, /\n\n<\/details>\n\n$/) + const inner = block.replace(/^\n[^\n]*<\/summary>\n\n/, '').replace(/\n\n<\/details>\n\n$/, '') + const paragraphs = inner.split('\n\n') + assert.ok(paragraphs.length > 1, 'a folded description is regrouped into paragraphs') + assert.equal(paragraphs.join(' ').replace(/\s+/g, ' '), text.replace(/\s+/g, ' ')) +}) + +test('short details and authored structure stay in place', () => { + assert.equal(detailsBlock('Keys are never returned.'), 'Keys are never returned.\n\n') + assert.equal(detailsBlock('Saves an Agent.\n\n- Limit one.\n- Limit two.'), 'Saves an Agent.\n\n- Limit one.\n- Limit two.\n\n') + assert.equal(detailsBlock(''), '') +}) + +test('a lead loses inline markdown because page descriptions are plain text', () => { + assert.equal(plainText('With `stream=true`, see **[Request conventions](/request-conventions)**.'), 'With stream=true, see Request conventions.') +}) + +test('contract markdown is escaped for MDX outside code spans only', () => { + assert.equal(mdxText('an empty body is {} and `{}` or '), 'an empty body is {} and `{}` or <key>') +}) test('public rendering preserves operation prose, schemas and project authentication', () => { const fixture = { swagger: '2.0', info: { title: 'Example', version: '1' }, basePath: '/v1', paths: { diff --git a/apps/docs/scripts/generate-api-reference.mjs b/apps/docs/scripts/generate-api-reference.mjs index b9b706b46..bad7f396c 100644 --- a/apps/docs/scripts/generate-api-reference.mjs +++ b/apps/docs/scripts/generate-api-reference.mjs @@ -1,12 +1,18 @@ #!/usr/bin/env node // Render the actual contracts without copying prose from superseded API surfaces. +// +// One page per operation, in one folder per tag. A page renders a single +// operation: a whole tag on one page (up to 11 operations with their full +// request and response schemas) took 4-10 seconds to render and weighed +// 1.4-1.8 MB, which stalled navigation. Each tag folder keeps an overview page +// at the former tag URL, so /api-reference/sessions still resolves. import { generateFilesOnly } from 'fumadocs-openapi' import { createOpenAPI } from 'fumadocs-openapi/server' import yaml from 'js-yaml' import fs from 'node:fs' import path from 'node:path' import crypto from 'node:crypto' -import { appRoot, repoRoot, surfaces, sourcePath, normalise } from './contracts.mjs' +import { appRoot, repoRoot, surfaces, sourcePath, normalise, methods, splitDescription, detailsBlock, plainText, fullPath } from './contracts.mjs' const root = path.join(appRoot, 'content/docs/api-reference') fs.rmSync(root, { recursive: true, force: true }) fs.mkdirSync(root, { recursive: true }) @@ -14,25 +20,106 @@ fs.rmSync(path.join(appRoot, 'openapi'), { recursive: true, force: true }) fs.mkdirSync(path.join(appRoot, 'openapi')) const record = { sources: {}, outputs: {} } const digest = file => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') +const slug = text => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') +// Record keys are POSIX paths, so a record generated on Linux verifies on Windows. +const key = (from, file) => path.relative(from, file).split(path.sep).join('/') +const write = (file, text) => { + fs.mkdirSync(path.dirname(file), { recursive: true }) + fs.writeFileSync(file, text) + record.outputs[key(appRoot, file)] = digest(file) +} +const yamlString = text => JSON.stringify(text) + +// The lead goes under the title and into search metadata; the details render in +// the page body above the request. +function withSplitDescription(content) { + const match = /^---\n([\s\S]*?)\n---\n/.exec(content) + if (!match) throw new Error('Generated page without frontmatter') + const frontmatter = yaml.load(match[1]) + const { lead, details } = splitDescription(frontmatter.description) + frontmatter.description = plainText(lead) + const body = content.slice(match[0].length) + const at = body.indexOf(' s.directory === '/' + folder)) throw new Error(`Tag ${JSON.stringify(tag)} collides with the ${folder} reference.`) + folderOf.set(folder, tag) + } + const pageOf = new Map() + for (const { folder, operations } of tags.values()) { + const taken = new Set() + for (const entry of operations) { + const name = slug(entry.operation.summary || `${entry.method} ${entry.route}`) + if (taken.has(name)) throw new Error(`Two ${folder} operations share the page name ${name}; give them distinct summaries.`) + taken.add(name) + pageOf.set(`${entry.method} ${entry.route}`, { folder, name }) + } + } + const files = await generateFilesOnly({ + input: createOpenAPI({ input: [output] }), + per: 'operation', + groupBy: 'tag', + slugify: slug, + name: entry => { + const page = pageOf.get(`${entry.item.method} ${entry.item.path}`) + if (!page) throw new Error('Unexpected generated entry: ' + JSON.stringify(entry.item)) + return page.name + }, + }) const directory = root + surface.directory - fs.mkdirSync(directory, { recursive: true }) + const expected = new Set([...pageOf.values()].map(page => `${page.folder}/${page.name}.mdx`)) for (const file of files) { - const target = path.join(directory, file.path) - fs.writeFileSync(target, file.content.replace(/document=\{[^}]*\}/, `document={${JSON.stringify(surface.id)}}`)) - record.outputs[path.relative(appRoot, target)] = digest(target) + const relative = file.path.split(path.sep).join('/') + if (!expected.delete(relative)) throw new Error('Unexpected generated page: ' + relative) + write(path.join(directory, relative), withSplitDescription(file.content).replace(/document=\{[^}]*\}/, `document={${JSON.stringify(surface.id)}}`)) + } + if (expected.size) throw new Error('Operations without a generated page: ' + [...expected].join(', ')) + const pages = pageOf.size + // Each tag folder: an overview at the tag URL and the operations in contract order. + for (const [tag, { folder, operations }] of tags) { + const rows = operations.map(({ route, method, operation }) => { + const page = pageOf.get(`${method} ${route}`) + return `| [${operation.summary ?? route}](/api-reference${surface.directory}/${folder}/${page.name}) | \`${method.toUpperCase()}\` | \`${fullPath(surface, route)}\` |` + }) + const description = `${tag}. ${surface.title}: ${surface.credential}.` + write(path.join(directory, folder, 'index.mdx'), `---\ntitle: ${yamlString(tag)}\ndescription: ${yamlString(description)}\n---\n\n${surface.authority}\n\n| Operation | Method | Path |\n| --- | --- | --- |\n${rows.join('\n')}\n`) + // Leaving index out of pages makes it the folder's own link: the tag name + // opens the overview and expands the operations. + write(path.join(directory, folder, 'meta.json'), JSON.stringify({ title: tag, pages: operations.map(({ route, method }) => pageOf.get(`${method} ${route}`).name) }, null, 2) + '\n') } - const pages = ['index', ...files.map(file => file.path.replace(/\.mdx$/, ''))] - if (!surface.directory) pages.push('core', 'machine') - fs.writeFileSync(path.join(directory, 'meta.json'), JSON.stringify({ title: surface.title, pages }, null, 2) + '\n') - const body = `---\ntitle: ${surface.title}\ndescription: ${surface.prefix} — ${surface.credential}.\n---\n\n${surface.authority}\n\n**Credential:** ${surface.credential}. Examples use reserved \`example.com\` origins. This reference does not send requests or collect credentials.\n\n${surface.id === 'runtime-api' ? '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).\n\n' : ''}${surface.id === 'core-api' ? '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.\n\n' : ''}[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine)\n\n` + files.map(file => `- [${file.path.replace(/\.mdx$/, '')}](/api-reference${surface.directory}/${file.path.replace(/\.mdx$/, '')})`).join('\n') + '\n' - fs.writeFileSync(path.join(directory, 'index.mdx'), body) - record.sources[path.relative(repoRoot, sourcePath(surface))] = digest(sourcePath(surface)) - record.outputs[path.relative(appRoot, output)] = digest(output) - for (const name of ['meta.json', 'index.mdx']) record.outputs[path.relative(appRoot, path.join(directory, name))] = digest(path.join(directory, name)) - console.log(surface.id + ': ' + files.length + ' tag pages') + const folders = [...tags.values()].map(tag => tag.folder) + // As in tag folders, the surface overview is the folder's own link. + const meta = [...folders] + if (!surface.directory) meta.push('core', 'machine') + write(path.join(directory, 'meta.json'), JSON.stringify({ title: surface.title, pages: meta }, null, 2) + '\n') + const body = `---\ntitle: ${surface.title}\ndescription: ${surface.prefix} — ${surface.credential}.\n---\n\n${surface.authority}\n\n**Credential:** ${surface.credential}. Examples use reserved \`example.com\` origins. This reference does not send requests or collect credentials.\n\n${surface.id === 'runtime-api' ? 'This schema covers node configuration, enrollment and identity, and native Runtime installation. Daemon WebSockets and executor connection details are described in the [machine overview](/public-api#machine-connection-api).\n\n' : ''}${surface.id === 'core-api' ? '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.\n\n' : ''}[API namespaces and credentials](/public-api) · [Application reference](/api-reference) · [Administration reference](/api-reference/core) · [Machine reference](/api-reference/machine) · [Error codes](/error-codes)\n\n` + [...tags].map(([tag, { folder, operations }]) => `- [${tag}](/api-reference${surface.directory}/${folder}) · ${operations.length} ${operations.length === 1 ? 'operation' : 'operations'}`).join('\n') + '\n' + write(path.join(directory, 'index.mdx'), body) + record.sources[key(repoRoot, sourcePath(surface))] = digest(sourcePath(surface)) + record.outputs[key(appRoot, output)] = digest(output) + console.log(`${surface.id}: ${pages} operation pages in ${tags.size} tags`) } fs.writeFileSync(path.join(appRoot, 'openapi/sources.json'), JSON.stringify(record, null, 2) + '\n') diff --git a/apps/docs/scripts/generate-guides.mjs b/apps/docs/scripts/generate-guides.mjs index 4b6ef85e3..c55afe7a3 100644 --- a/apps/docs/scripts/generate-guides.mjs +++ b/apps/docs/scripts/generate-guides.mjs @@ -43,7 +43,7 @@ for (const guide of guides) { } return label + '(' + url + (anchor ? '#' + anchor : '') + ')' }) - const en = `---\ntitle: ${JSON.stringify(guide.title)}\ndescription: ${JSON.stringify(guide.description)}\n---\n\n` + (guide.slug === 'execution-model' ? '![Application, administration and machine credential boundaries](/images/architecture.svg)\n\n' : '') + mdx(body.trim()) + `\n\n[Repository source](${sourceURL(guide.source)})\n` + const en = `---\ntitle: ${JSON.stringify(guide.title)}\ndescription: ${JSON.stringify(guide.description)}\n---\n\n` + mdx(body.trim()) + `\n\n[Repository source](${sourceURL(guide.source)})\n` const relative = `content/docs/${guide.slug}.mdx` fs.writeFileSync(path.join(app, relative), en) record.outputs[relative] = digest(en) diff --git a/apps/docs/scripts/guides.json b/apps/docs/scripts/guides.json index 5ef23e97a..991dd1562 100644 --- a/apps/docs/scripts/guides.json +++ b/apps/docs/scripts/guides.json @@ -12,10 +12,10 @@ "description": "Projects, credentials and the boundary between applications, administration and execution." }, { - "slug": "execution-model", - "source": "docs/web/architecture.md", - "title": "Execution and API architecture", - "description": "Applications call the public API; the administrator browser calls Web; Runtime connects to Core." + "slug": "architecture", + "source": "docs/architecture.md", + "title": "Architecture", + "description": "Core, the Runtime daemon and the native harness: the three namespaces, replaceable parts and a Session end to end." }, { "slug": "install", @@ -53,6 +53,12 @@ "title": "API namespaces and credentials", "description": "The public application API, private administration API and machine connection interface." }, + { + "slug": "request-conventions", + "source": "docs/api/request-conventions.md", + "title": "Request conventions", + "description": "Headers, JSON body checks, list parameters and errors shared by every /v1 operation." + }, { "slug": "agents-and-tools", "source": "contracts/agents-api/execution-tools.md", @@ -110,6 +116,12 @@ "title": "Core administration API", "description": "Management operations and their server-side credential boundary." }, + { + "slug": "error-codes", + "source": "contracts/agents-api/error-codes.md", + "title": "Error codes", + "description": "Every error code Core, the console and the machine transport write, and what each means." + }, { "slug": "observability", "source": "contracts/agents-api/runtime-observability-api.md", diff --git a/apps/docs/scripts/test_contract_routes.py b/apps/docs/scripts/test_contract_routes.py index 243b9dd75..d6f8b3050 100644 --- a/apps/docs/scripts/test_contract_routes.py +++ b/apps/docs/scripts/test_contract_routes.py @@ -19,6 +19,12 @@ def test_nested_registration_inherits_parent_scope(self): child = routes.Region('r.Get("/projects/{project_id}", h.getProject)') self.assertEqual(child.routes({"r": "/core/v1"}), [("/core/v1/projects/{project_id}", "GET")]) + def test_transport_paths_are_all_accounted_for(self): + registered = routes.transport_paths() + self.assertIn("/api/v1/sandbox-node/connect", registered) + self.assertIn("/api/v1/agent-daemon/ws", registered) + self.assertEqual(registered, set(routes.TRANSPORT)) + def test_unrelated_router_does_not_acquire_a_prefix(self): region = routes.Region('unknown.Get("/projects", handler)') self.assertEqual(region.routes({"r": "/core/v1"}), []) diff --git a/apps/docs/scripts/verify-api-copy.mjs b/apps/docs/scripts/verify-api-copy.mjs index 743a100ef..d1fa5d381 100644 --- a/apps/docs/scripts/verify-api-copy.mjs +++ b/apps/docs/scripts/verify-api-copy.mjs @@ -1,25 +1,44 @@ #!/usr/bin/env node -// Compare every rendered operation and schema with the current contract projection. +// Compare every rendered operation and schema with the current contract projection, +// and every tag folder's navigation and overview with its operation pages. import fs from 'node:fs' import path from 'node:path' import yaml from 'js-yaml' import assert from 'node:assert/strict' -import { appRoot, surfaces, normalise, methods } from './contracts.mjs' +import { appRoot, surfaces, normalise, methods, fullPath } from './contracts.mjs' let count = 0 for (const surface of surfaces) { const actual = yaml.load(fs.readFileSync(path.join(appRoot, 'openapi', surface.id + '.yaml'), 'utf8')) assert.deepEqual(actual, normalise(surface), surface.id + ': rendered contract differs') const listed = [] const dir = path.join(appRoot, 'content/docs/api-reference') + surface.directory - for (const name of fs.readdirSync(dir).filter(n => n.endsWith('.mdx') && n !== 'index.mdx')) { - const content = fs.readFileSync(path.join(dir, name), 'utf8') - assert.ok(content.includes('document={' + JSON.stringify(surface.id) + '}'), 'Wrong reference credential surface: ' + name) - const operations = content.match(/operations=\{(\[[\s\S]*?\])\}/) - assert.ok(operations, 'Missing operations: ' + name) - for (const op of JSON.parse(operations[1])) listed.push(op.method + ' ' + op.path) + // Operation pages live one level down, in a folder per tag; index.mdx files + // are overviews. Other surfaces' directories (core, machine) are skipped. + const other = new Set(surfaces.filter(s => s.directory && s !== surface).map(s => s.directory.slice(1))) + const folders = fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory() && !other.has(e.name)).map(e => e.name) + const routes = new Set(Object.entries(actual.paths).flatMap(([route, item]) => methods.filter(m => item[m]).map(m => `${m.toUpperCase()} ${fullPath(surface, route)}`))) + for (const folder of folders) { + const folderDir = path.join(dir, folder) + const pages = fs.readdirSync(folderDir).filter(n => n.endsWith('.mdx') && n !== 'index.mdx').map(n => n.slice(0, -4)) + // The sidebar shows exactly the folder's pages; a page missing from meta.json is unreachable. + const meta = JSON.parse(fs.readFileSync(path.join(folderDir, 'meta.json'), 'utf8')) + assert.deepEqual([...meta.pages].sort(), [...pages].sort(), `${surface.id}/${folder}: meta.json pages differ from its operation pages`) + // The overview links every page once, with the path a caller sends. + const overview = fs.readFileSync(path.join(folderDir, 'index.mdx'), 'utf8') + const rows = [...overview.matchAll(/^\| \[[^\]]*\]\(([^)]+)\) \| `([A-Z]+)` \| `([^`]+)` \|$/gm)] + assert.deepEqual(rows.map(r => r[1].split('/').pop()).sort(), [...pages].sort(), `${surface.id}/${folder}: overview rows differ from its operation pages`) + for (const [, , method, route] of rows) assert.ok(routes.has(`${method} ${route}`), `${surface.id}/${folder}: overview lists ${method} ${route}, which the contract does not publish`) + for (const name of pages) { + const content = fs.readFileSync(path.join(folderDir, name + '.mdx'), 'utf8') + assert.ok(content.includes('document={' + JSON.stringify(surface.id) + '}'), 'Wrong reference credential surface: ' + folder + '/' + name) + const operations = content.match(/operations=\{(\[[\s\S]*?\])\}/) + assert.ok(operations, 'Missing operations: ' + folder + '/' + name) + for (const op of JSON.parse(operations[1])) listed.push(op.method + ' ' + op.path) + } } const expected = Object.entries(actual.paths).flatMap(([route, item]) => methods.filter(m => item[m]).map(m => m + ' ' + route)) assert.deepEqual([...new Set(listed)].sort(), expected.sort(), 'Missing or obsolete API page: ' + surface.id) + assert.equal(listed.length, expected.length, 'An operation has more than one page: ' + surface.id) count += expected.length } -console.log(count + ' operations, schemas, descriptions and credential surfaces match current contracts.') +console.log(count + ' operations, schemas, descriptions, navigation, overviews and credential surfaces match current contracts.') diff --git a/apps/docs/scripts/verify-contract-freshness.mjs b/apps/docs/scripts/verify-contract-freshness.mjs index 785c6dc3c..d72357523 100644 --- a/apps/docs/scripts/verify-contract-freshness.mjs +++ b/apps/docs/scripts/verify-contract-freshness.mjs @@ -10,7 +10,8 @@ assert.deepEqual(Object.keys(record.sources).sort(), surfaces.map(s => 'contract function filesUnder(directory) { return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => { const file = path.join(directory, entry.name) - return entry.isDirectory() ? filesUnder(file) : [path.relative(appRoot, file)] + // Record keys are POSIX paths on every platform. + return entry.isDirectory() ? filesUnder(file) : [path.relative(appRoot, file).split(path.sep).join('/')] }) } const rendered = [...filesUnder(path.join(appRoot, 'openapi')), ...filesUnder(path.join(appRoot, 'content/docs/api-reference'))] diff --git a/apps/docs/scripts/verify-contract-routes.py b/apps/docs/scripts/verify-contract-routes.py index c9f51d2f5..836e0b9dd 100644 --- a/apps/docs/scripts/verify-contract-routes.py +++ b/apps/docs/scripts/verify-contract-routes.py @@ -41,6 +41,31 @@ IGNORED = {("/healthz", "GET"): "liveness probe, not part of the Agent API"} +# Machine transport served beside the API router by cmd/server. These are not +# REST operations and no OpenAPI contract publishes them; each must be named in +# the API index. Their error shapes are listed in contracts/agents-api/error-codes.md +# and checked by the Go registry tests, not here. +SERVER = REPO / "services/agents-api/cmd/server/http_routes.go" +GATEWAY = REPO / "internal/agentdaemon/gateway/routes.go" +# The Runtime gateway mounts the daemon routes under this prefix. +GATEWAY_MOUNT = REPO / "services/agents-api/internal/runtime/gateway.go" +MOUNT = re.compile(r"\.Route\(\s*\"([^\"]+)\"\s*,\s*func\([^)]*\)\s*\{\s*gateway\.RegisterRoutes\(") +INDEX = REPO / "docs/api/README.md" +# mux.Handle or mux.HandleFunc, with the handler expression. +MUX = re.compile(r"\bmux\.Handle(?:Func)?\(\s*\"([^\"]+)\"\s*,\s*([\w.]+)") +# A chi Handle or HandleFunc mounts a non-REST handler, such as static artifacts. +CHI_HANDLE = re.compile(r"\b\w+\.Handle(?:Func)?\(\s*\"(/api/v1/[^\"]+)\"") +TRANSPORT = { + "/api/v1/agent-daemon/": "prefix of the daemon gateway routes below", + "/api/v1/agent-daemon/enroll": "self-hosted executor enrollment; plain-text errors", + "/api/v1/agent-daemon/connection": "self-hosted executor connection check; plain-text errors", + "/api/v1/agent-daemon/ws": "daemon WebSocket", + "/api/v1/agent-daemon/bootstrap": "daemon bootstrap", + "/api/v1/agent-daemon/device-status": "daemon self-check", + "/api/v1/sandbox-node/connect": "node WebSocket; plain-text errors", + "/api/v1/agent-daemon/install/": "public immutable native installer artifacts", +} + # Differences between the contract and the registered route that the reference # accepts on purpose, keyed (path, method) as the contract spells them. ACCEPTED = {} @@ -190,7 +215,7 @@ def main() -> int: base = (document.get("basePath") or "").rstrip("/") for route, item in (document.get("paths") or {}).items(): for method in item: - if method in ("get", "post", "put", "patch", "delete", "head", "options"): + if method in ("get", "post", "put", "patch", "delete", "head", "options", "trace"): documented.setdefault(((base + route) or "/", method.upper()), label) guard_paths = set() @@ -220,7 +245,47 @@ def main() -> int: print(" %-6s %-72s [%s]" % (method, path, documented[(path, method)])) for path, method in accepted: print(" ok %-72s %s" % (path, ACCEPTED[(path, method)])) - return 1 if real or undocumented else 0 + print() + transport_problems = check_transport() + return 1 if real or undocumented or transport_problems else 0 + + +def transport_paths() -> set[str]: + """Paths cmd/server mounts beside the API, plus the daemon gateway routes.""" + server = SERVER.read_text(encoding="utf-8") + # Paths handed back to the API router are API routes, checked by [A] and [B]. + paths = {path for path, handler in MUX.findall(server) if path != "/" and handler != "apiHandler"} + for name in sorted(API.glob("*.go")): + if not name.name.endswith("_test.go"): + paths.update(path.rstrip("*") for path in CHI_HANDLE.findall(name.read_text(encoding="utf-8"))) + mounts = MOUNT.findall(GATEWAY_MOUNT.read_text(encoding="utf-8")) + if len(mounts) != 1: + raise ValueError("expected one gateway.RegisterRoutes mount in " + str(GATEWAY_MOUNT)) + gateway = Region(GATEWAY.read_text(encoding="utf-8")) + paths.update(path for path, _ in gateway.routes({"r": mounts[0]})) + return paths + + +def check_transport() -> int: + registered = transport_paths() + index = INDEX.read_text(encoding="utf-8") + problems = [] + for path in sorted(registered - TRANSPORT.keys()): + problems.append("registered transport path with no TRANSPORT entry: " + path) + for path in sorted(TRANSPORT.keys() - registered): + problems.append("TRANSPORT entry no longer registered: " + path) + for path in sorted(registered & TRANSPORT.keys()): + tail = path[len("/api/v1/"):].rstrip("/") + # The index names each route in backticks, optionally after its method. + mention = re.compile(r"`(?:[A-Z]+ )?" + re.escape(tail) + r"`") + if not path.endswith("/") and not mention.search(index): + problems.append("transport path missing from docs/api/README.md: " + path) + print(" [C] Machine transport outside the contracts: %d (%d problems)" % (len(registered), len(problems))) + for path in sorted(registered & TRANSPORT.keys()): + print(" ok %-72s %s" % (path, TRANSPORT[path])) + for problem in problems: + print(" " + problem) + return len(problems) if __name__ == "__main__": diff --git a/apps/docs/scripts/verify-docs-facts.mjs b/apps/docs/scripts/verify-docs-facts.mjs index ccf9b0b4c..2e7272594 100644 --- a/apps/docs/scripts/verify-docs-facts.mjs +++ b/apps/docs/scripts/verify-docs-facts.mjs @@ -26,5 +26,16 @@ for (const file of fs.readdirSync(path.join(app, 'content/docs')).filter(n => n. const text = fs.readFileSync(path.join(app, 'content/docs', file), 'utf8') for (const retired of ['/core/v1/admin', 'sandbox-manager.openapi.yaml']) assert.ok(!text.includes(retired), 'Obsolete claim in ' + file + ': ' + retired) } +// The sidebar is built from this list, so a page missing from it is reachable +// only by direct link. fumadocs adds unlisted files back only for the "..." +// placeholder, which this tree does not use. +const navigation = JSON.parse(fs.readFileSync(path.join(app, 'content/docs/meta.json'))).pages +const docsDir = path.join(app, 'content/docs') +for (const entry of fs.readdirSync(docsDir, { withFileTypes: true })) { + if (entry.name === 'meta.json') continue + const slug = entry.isDirectory() ? entry.name : entry.name.replace(/\.mdx$/, '') + if (!entry.isDirectory() && !entry.name.endsWith('.mdx')) continue + assert.ok(navigation.includes(slug), 'Page is missing from the sidebar (content/docs/meta.json): ' + slug) +} assert.deepEqual(fs.readFileSync(path.join(app, 'app/icon.svg')), fs.readFileSync(path.join(repo, 'apps/web/public/favicon.svg')), 'Docs favicon must match the approved Web asset') console.log('Guide copies, source authority and namespace/configuration facts are current.') diff --git a/apps/docs/scripts/verify-error-codes.mjs b/apps/docs/scripts/verify-error-codes.mjs new file mode 100644 index 000000000..46450e99b --- /dev/null +++ b/apps/docs/scripts/verify-error-codes.mjs @@ -0,0 +1,138 @@ +#!/usr/bin/env node +// Keep client-side error codes tied to the registry: codes the TypeScript +// client creates itself and codes the client and Web compare against. +// +// This is half of the registry check. The other half, every status and code the +// Go services write, is services/agents-api/internal/api/contract_conformance_test.go, +// which runs in `make check-agents-api`, not in `pnpm verify`. Both run in CI. +import fs from 'node:fs' +import path from 'node:path' +import assert from 'node:assert/strict' +import { repoRoot } from './contracts.mjs' + +const registry = fs.readFileSync(path.join(repoRoot, 'contracts/agents-api/error-codes.md'), 'utf8') + +// Codes by registry section, from the code column of each table row. +const sections = new Map() +let heading = null +for (const line of registry.split('\n')) { + if (line.startsWith('## ')) { heading = line.slice(3).trim(); sections.set(heading, new Set()); continue } + const cells = line.split('|').map(cell => cell.trim()) + if (!heading || cells.length < 3) continue + for (const cell of cells.slice(1, 3)) { + const match = /^`([a-z0-9_]+)`$/.exec(cell) + if (match) { sections.get(heading).add(match[1]); break } + } +} +const known = new Set([...sections.values()].flatMap(set => [...set])) + +// Session diagnostic categories are not HTTP codes; core-errors.md owns them. +const coreErrors = fs.readFileSync(path.join(repoRoot, 'contracts/agents-api/core-errors.md'), 'utf8') +const diagnostics = /^## Diagnostic failure categories\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(coreErrors) +assert.ok(diagnostics, 'core-errors.md has no Diagnostic failure categories section') +for (const match of diagnostics[1].matchAll(/^\| `([a-z0-9_]+)` \|/gm)) known.add(match[1]) + +// Codes Web still compares against although nothing emits them, with the owner's +// follow-up. An entry here is a known defect, not an accepted code. +const retired = new Map() + +function sources(directory) { + return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => { + const file = path.join(directory, entry.name) + if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : sources(file) + return /\.(ts|tsx)$/.test(entry.name) && !/\.test\.(ts|tsx)$/.test(entry.name) ? [file] : [] + }) +} + +// Top-level arguments of the call whose "(" is at index open. Strings, +// template literals and nested brackets are skipped; this is enough for the +// client sources, which a type checker already keeps well formed. +function callArguments(text, open) { + const args = [] + let depth = 0, start = open + 1, quote = null + for (let i = open; i < text.length; i++) { + const c = text[i] + if (quote) { + if (c === '\\') i++ + else if (c === quote) quote = null + continue + } + if (c === '"' || c === "'" || c === '`') quote = c + else if ('([{'.includes(c)) depth++ + else if (')]}'.includes(c)) { + depth-- + if (depth === 0) { args.push(text.slice(start, i).trim()); return Object.assign(args.filter(a => a !== ''), { end: i }) } + } else if (c === ',' && depth === 1) { args.push(text.slice(start, i).trim()); start = i + 1 } + } + return args +} +const literal = arg => /^"([a-z0-9_]+)"$/.exec(arg ?? '')?.[1] +const calls = (text, name) => [...text.matchAll(new RegExp(`(?()]*>)?\\s*\\(`, 'g'))] + .map(match => callArguments(text, match.index + match[0].length - 1)) + +const files = ['packages/agents-client/src', 'apps/web/src'].flatMap(root => sources(path.join(repoRoot, root))) + .map(file => ({ file, text: fs.readFileSync(file, 'utf8') })) + +// A forwarder is a function that passes one of its parameters on as an +// AgentCoreError code, directly or through another forwarder. Codes given to a +// forwarder as literals are created codes as well. +const forwarders = new Map([['AgentCoreError', 2]]) // new AgentCoreError(message, status, code, param?) +const definitions = files.flatMap(({ text }) => [...text.matchAll(/\bfunction\s+(\w+)\s*(?:<[^()]*>)?\s*\(/g)].map(match => { + const open = match.index + match[0].length - 1 + const list = callArguments(text, open) + const params = list.map(param => /^(?:\.\.\.)?(\w+)/.exec(param)?.[1]) + // A return type may itself be an object type, so the body is taken up to the + // function's closing brace at column 0 rather than from the first "{". + const start = list.end ?? open + const close = text.indexOf('\n}', start) + return { name: match[1], params, body: text.slice(start, close < 0 ? text.length : close + 2) } +})) +for (let changed = true; changed;) { + changed = false + for (const { name, params, body } of definitions) { + if (forwarders.has(name)) continue + for (const [target, index] of forwarders) { + const forwarded = calls(body, target).map(args => params.indexOf(args[index])).find(position => position >= 0) + if (forwarded !== undefined) { forwarders.set(name, forwarded); changed = true; break } + } + } +} + +const created = new Map() +const compared = new Map() +const note = (map, code, file) => map.set(code, [...(map.get(code) ?? []), path.relative(repoRoot, file)]) +for (const { file, text } of files) { + for (const [name, index] of forwarders) { + for (const args of calls(text, name)) { + const code = literal(args[index]) + if (code) note(created, code, file) + } + } + for (const match of text.matchAll(/(typeof\s+[\w.?]*)?\bcode\s*[!=]==?\s*"([a-z0-9_]+)"|"([a-z0-9_]+)"\s*[!=]==?\s*[\w.?]*\bcode\b/g)) { + if (match[1]) continue // typeof value.code === "string" checks a type, not a code + note(compared, match[2] ?? match[3], file) + } +} + +const client = sections.get('Client-generated codes') +assert.ok(client, 'error-codes.md has no Client-generated codes section') +const server = new Set([...sections].filter(([name]) => name !== 'Client-generated codes').flatMap(([, codes]) => [...codes])) +const problems = [] +for (const [code, sites] of created) { + // The client may rebuild a Core error with the same code, dropping unsafe fields. + if (!client.has(code) && !server.has(code)) problems.push(`client creates ${code} (${[...new Set(sites)].join(', ')}) but the Client-generated codes table does not list it`) +} +for (const code of client) { + if (!created.has(code)) problems.push(`Client-generated codes lists ${code}, which no client source creates`) + if (server.has(code)) problems.push(`${code} is listed both as a Core code and as client-generated`) +} +for (const [code, files] of compared) { + if (!known.has(code) && !retired.has(code)) problems.push(`${[...new Set(files)].join(', ')} compares against ${code}, which error-codes.md does not list`) +} +for (const [code, reason] of retired) { + if (known.has(code)) problems.push(`${code} is listed in error-codes.md; remove it from the retired list`) + if (!compared.has(code)) problems.push(`${code} is no longer compared; remove it from the retired list`) + else console.warn('Known defect: ' + reason) +} +assert.deepEqual(problems, [], 'Error code registry is out of date:\n' + problems.join('\n')) +console.log(`${created.size} client-created codes (through ${forwarders.size - 1} forwarding helpers) and ${compared.size} compared codes match the registry.`) diff --git a/contracts/agents-api/admin-api.md b/contracts/agents-api/admin-api.md index 87b6b6b5c..d9ddf21ce 100644 --- a/contracts/agents-api/admin-api.md +++ b/contracts/agents-api/admin-api.md @@ -66,9 +66,34 @@ unusable key before issuing another; plaintext cannot be recovered. Paths below are relative to `/projects/{project_id}`. The Project selects a tenant, including an archived Project; it does not authenticate. Shared resource handlers preserve their -public object serialization, pagination, errors and deletion preconditions. They +public object serialization, cursors, ordering and deletion preconditions; Skill +list bounds differ as the table below shows. They receive an explicit target tenant, not a fabricated caller identity. +Errors use the [Core envelope](core-errors.md). The shared list parser and +not-found mapping choose their error fields by request path, so every Core +resource route gets the Agents API Beta fields for those cases. For Agents, +Templates, Vaults, Credentials and Sessions this is the same family their `/v1` +routes use. Files and Skills differ: their `/v1` routes keep the separately +observed Files and Skills fields ([list query semantics](list-query-semantics.md)), +which the Core routes do not reproduce. Errors a handler writes directly keep +their `/v1` fields on both namespaces: an unknown Files `purpose` filter is 400 +with a null code and param `purpose`, and deleting the default Skill version is +400 `invalid_value` with param `version`. + +| Case | `/v1/files`, `/v1/skills` | Core `/files`, `/skills` | +| --- | --- | --- | +| Missing resource | 404, null `code` (Files: param `id`) | 404, `not_found_error` (Files: param `id`) | +| Unresolved Skill version `after` | 400 `invalid_value`, param `after` | 400 `invalid_request_error`, null param | +| Repeated list key | Files 400 `unsupported_parameter`; Skills 400 `duplicate_parameter` with the key as param | 400 `invalid_request_error`, null param | +| Invalid `order` | Files 400 with null `code`; Skills 400 `invalid_value`, param `order` | 400 `invalid_request_error`, null param | +| `limit` out of range | Files 400 with null `code`; Skills `integer_below_min_value` or `integer_above_max_value`, param `limit` | 400 `invalid_request_error`, null param | +| Skills `limit=0` | Empty page | 400 `invalid_request_error`; Core Skill lists accept 1–100 | + +Storage availability codes are the same on both namespaces: `file_storage_unavailable`, +`skill_storage_unavailable` and `file_transfer_unavailable` (503). The +[error code registry](error-codes.md) lists every code. + | Resource | GET routes | DELETE routes | | --- | --- | --- | | Agents | `/agents`, `/agents/{agent_id}` | `/agents/{agent_id}` | diff --git a/contracts/agents-api/core-errors.md b/contracts/agents-api/core-errors.md index 774123304..c3338c28a 100644 --- a/contracts/agents-api/core-errors.md +++ b/contracts/agents-api/core-errors.md @@ -50,7 +50,8 @@ through the proxy; the console does not reinterpret their codes or details. The first three use `type: "invalid_request_error"`; the last uses `type: "server_error"`. A Core `401 invalid_admin_key` remains distinguishable from a missing console sign-in. `/console/auth` keeps its existing -`{"error":"…"}` errors. Bare, retired and direct public/machine paths do not +`{"error":"…"}` errors without a code; their statuses are listed under +[console sign-in responses](error-codes.md#console-sign-in-responses). Bare, retired and direct public/machine paths do not become proxyable operations. Host, origin, authentication, credential stripping, path checks and the no-retry rule are unchanged. @@ -185,3 +186,7 @@ Model configuration writes additionally return `model_configuration_model_invali with `param: model`, or `harness_config_invalid` with `param: harness_config`. Both carry fixed messages without submitted values. Existing provider field errors retain their field params within the `model_provider` object. + +The [error code registry](error-codes.md) lists every code Core and the console +write, separates them from node diagnostics and client-generated codes, and is +checked against the code in both directions. diff --git a/contracts/agents-api/core.openapi.yaml b/contracts/agents-api/core.openapi.yaml index decee3473..c4d3b261a 100644 --- a/contracts/agents-api/core.openapi.yaml +++ b/contracts/agents-api/core.openapi.yaml @@ -3618,7 +3618,7 @@ paths: name: harness required: true type: string - - description: Complete model provider bundle + - description: Complete model configuration in: body name: body required: true @@ -3792,6 +3792,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -3840,6 +3844,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -4247,6 +4255,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -4326,6 +4338,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Get a self_hosted Session's installation commands @@ -4572,6 +4588,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -5356,6 +5376,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' "503": description: Service Unavailable schema: @@ -5579,10 +5603,10 @@ paths: name: after type: string - default: 20 - description: Page size; 0 returns an empty page + description: Page size, 1–100 in: query maximum: 100 - minimum: 0 + minimum: 1 name: limit type: integer - description: Creation order; omit for descending, explicit empty values are invalid @@ -5604,6 +5628,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillList' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: List Skills in a Project @@ -5630,6 +5674,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillDeleted' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Delete a Skill and its versions in a Project @@ -5655,6 +5719,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.Skill' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Retrieve Skill metadata in a Project @@ -5681,6 +5765,26 @@ paths: description: OK schema: type: file + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Download Skill content in a Project @@ -5700,10 +5804,10 @@ paths: name: after type: string - default: 20 - description: Page size; 0 returns an empty page + description: Page size, 1–100 in: query maximum: 100 - minimum: 0 + minimum: 1 name: limit type: integer - description: Version order; omit for descending, explicit empty values are invalid @@ -5725,6 +5829,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersionList' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: List Skill versions in a Project @@ -5756,6 +5880,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersionDeleted' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Delete a Skill version in a Project @@ -5786,6 +5930,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersion' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Retrieve Skill version metadata in a Project @@ -5817,6 +5981,26 @@ paths: description: OK schema: type: file + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/api.CoreErrorResponse' security: - DeploymentAdminAuth: [] summary: Download immutable Skill version content in a Project @@ -6287,6 +6471,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -6330,6 +6518,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -6414,6 +6606,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -6454,6 +6650,10 @@ paths: description: Unauthorized schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "503": description: Service Unavailable schema: @@ -6495,6 +6695,10 @@ paths: description: Unauthorized schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "503": description: Service Unavailable schema: @@ -6539,6 +6743,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: @@ -6723,6 +6931,10 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' "500": description: Internal Server Error schema: diff --git a/contracts/agents-api/environment-executor-credentials.md b/contracts/agents-api/environment-executor-credentials.md index e9f8a185f..e91670d61 100644 --- a/contracts/agents-api/environment-executor-credentials.md +++ b/contracts/agents-api/environment-executor-credentials.md @@ -130,6 +130,10 @@ When Core permanently rejects enrollment or the WebSocket, the daemon reports th reason and parks without retrying until stopped. A protocol mismatch requires the matching current distribution; it does not trigger a migration. Transient transport failures retain the existing reconnect behavior and never replay execution. +Enrollment and the connection check answer failures with a plain-text status body +and no error code, so the daemon decides by status alone; the WebSocket and +bootstrap handlers answer the failures they detect with +`{"error":"","detail":"…"}` ([registry](error-codes.md#runtime-daemon-transport-codes)). Rotate the same `key_id`, stop the daemon, replace the configured credential JSON file, and start it again. Issuing a new key for an enrolled Environment fails with diff --git a/contracts/agents-api/error-codes.md b/contracts/agents-api/error-codes.md new file mode 100644 index 000000000..e9dd98b2e --- /dev/null +++ b/contracts/agents-api/error-codes.md @@ -0,0 +1,292 @@ +# Error codes + +This registry lists every error `code` Core, the console (including the +installer rejections it relays) and the daemon transport write, the response shapes that carry no code, and the codes the +TypeScript client creates itself. Operation-specific triggers and `param` values +stay in the resource contracts; this page says what each code means and where it +can appear. + +Two checks compare it with the code. `contract_conformance_test.go` in +`services/agents-api/internal/api` requires the status and code of every row to +be written somewhere and every written status and code to have a row, and the +statuses of the uncoded tables to equal the statuses their handlers write. +`apps/docs/scripts/verify-error-codes.mjs` does the same for client-generated +codes and for every code the client and Web compare against, and the Go test +also compares the installation domain setup codes with the installer. The +Namespaces column tokens are checked in both files: `all`, or the namespaces +whose routes can answer with the code. + +## Which "code" is meant + +The word names eight different things. Only the first three are HTTP error codes. + +| Layer | Where it appears | Examples | Reference | +| --- | --- | --- | --- | +| API envelope | `error.code` of a `/v1`, `/core/v1` or `/api/v1` JSON error, or of an error object inside a Session event | `invalid_request_error`, `project_archived`, `stream_interrupted` | [HTTP API codes](#http-api-codes), [Session event codes](#session-event-error-codes) | +| Console envelope | `error.code` of an error Web's server writes for `/core/*` | `console_sign_in_required`, `core_unreachable` | [Console codes](#console-codes), [Core errors](core-errors.md) | +| Daemon transport | `error` member of an `/api/v1/agent-daemon/*` JSON error | `missing_bearer`, `incompatible_version` | [Runtime daemon transport codes](#runtime-daemon-transport-codes) | +| Runtime protocol result | `error_code` of a Core–Runtime message after connection, such as a workspace, preparation or cancellation result; Core validates each value against its message and maps it to its own outcome or stored cause; no API response returns it | `write_rejected`, `read_unconfirmed`, `cancel_timeout` | [Core–Runtime protocol](../../docs/runtime-protocol.md) and its typed payloads; not listed here | +| Node diagnostic | `diagnostic` value inside a node payload; never an HTTP status | `docker_unavailable`, `kvm_unavailable` | [Sandbox deployment](sandbox-deployment.md), [nodes](../../docs/getting-started/nodes.md) | +| Session diagnostic category | `code` of a failure category inside a successful Session diagnostics snapshot | `harness_error`, `runtime_disconnected` | [Diagnostic failure categories](core-errors.md#diagnostic-failure-categories) | +| Turn error | `error.code` of a failed Turn or subagent Turn in a successful read; Core always publishes `internal_error`, and the other values of the pinned enum are never returned | `internal_error` | The cause is in the [diagnostic failure categories](core-errors.md#diagnostic-failure-categories); not listed here | +| Client identifier | `AgentCoreError.code` created by `packages/agents-client` without a response, or a local daemon/adapter error | `sandbox_configuration_unconfirmed`, `invalid_admin_response` | [Client-generated codes](#client-generated-codes), daemon and adapter guides | + +`error.type` is not a second code. It follows one rule: `server_error` for any 5xx, +`conflict_error` for any 409, `not_found_error` or `invalid_beta` when the code is +that value, and `invalid_request_error` otherwise. + +## HTTP API codes + +`/v1`, `/core/v1` and `/api/v1` share one writer, so a code keeps its meaning in +every namespace; a row names a namespace-specific trigger where one differs. `/core/v1` adds optional `details` ([Core errors](core-errors.md)). +Clients branch on `code`, never on `message`. A `null` row is a response whose +`code` is null. + +| Status | Code | Namespaces | Meaning | +| --- | --- | --- | --- | +| 400 | `invalid_request_error` | all | Request validation failed: body fields, list queries on Agents API Beta lists and on the Core resource lists under `/projects/{project_id}`, cursors, MCP credential selection or unstorable text. `param` names the field when known | +| 400 | `invalid_request` | all | Malformed body, identifier or local request limit outside the official fields, including invalid queries on the Core Project, key, audit log and summary lists | +| 400 | `invalid_value` | `/v1`, `/core/v1` | Skills: invalid `order` or Skill version `after` on `/v1`; on both namespaces, deletion of the default Skill version (param `version`) | +| 400 | `duplicate_parameter` | `/v1` | Skills list key supplied more than once; `param` is the key | +| 400 | `integer_below_min_value` | `/v1` | Skills list `limit` below 0 | +| 400 | `integer_above_max_value` | `/v1` | Skills list `limit` above 100 | +| 400 | `unsupported_parameter` | `/v1`, `/core/v1` | A body on a deletion that accepts none, a repeated Files list key, or query parameters Runtime observation and history reads do not accept | +| 400 | `invalid_beta` | `/v1` | Missing or wrong `OpenAI-Beta: agents=v1` on an Agents API Beta route | +| 400 | `unsupported_or_invalid_configuration` | `/v1` | The configuration or input is outside what the selected harness supports | +| 400 | `model_provider_required` | `/v1` | The Session resolved no model provider and cannot run | +| 400 | `invalid_sandbox_configuration` | `/core/v1` | Sandbox deployment configuration is invalid | +| 400 | `invalid_name` | `/core/v1`, `/api/v1` | A Project, key or node name, including the name a node enrolls with, fails its length or character rules; on `/core/v1`, `details.max_length` gives the limit | +| 400 | `invalid_node_capacity` | `/core/v1` | Node `max_active` or `max_retained` is outside 1-1000000, or retained is below active | +| 400 | `invalid_model_provider` | `/core/v1` | The model configuration body is missing or malformed; a complete bundle is required | +| 400 | `model_provider_base_url_invalid` | `/core/v1` | `base_url` is not HTTPS, or carries credentials, a query or a fragment | +| 400 | `model_provider_protocol_unsupported` | `/core/v1` | The protocol is unknown or unsupported by the harness; `details.allowed_protocols` lists the supported ones | +| 400 | `model_provider_api_key_invalid` | `/core/v1` | The key is empty, longer than 16384 characters or contains a prohibited character | +| 400 | `model_provider_token_limits_invalid` | `/core/v1` | `context_window` or `max_output_tokens` is invalid, or missing where the harness requires it | +| 400 | `model_configuration_model_invalid` | `/core/v1` | `model` is not a nonempty model identifier | +| 400 | `harness_config_invalid` | `/core/v1` | `harness_config` contains unsupported or invalid native model parameters | +| 400 | `e2b_api_key_invalid` | `/core/v1` | E2B rejected the API key (param `e2b.api_key`) | +| 400 | `e2b_template_build_invalid` | `/core/v1` | The E2B template build is not a ready immutable build with matching resources (param `e2b.template`) | +| 400 | null | `/v1`, `/core/v1` | Files list range and order errors on `/v1`, an unknown Files `purpose` filter (param `purpose`) on both namespaces, and public download of a `user_data` File | +| 401 | `invalid_api_key` | `/v1` | Files or Skills rejected a supplied Bearer Project API key | +| 401 | `invalid_admin_key` | `/core/v1` | The Core key is missing or wrong | +| 401 | `invalid_node_credential` | `/api/v1` | The node enrollment token or node credential is missing or wrong | +| 401 | `installation_authorization_invalid` | `/api/v1` | The native installation authorization is invalid or expired; get a new command from the Session | +| 401 | null | `/v1` | No valid Bearer Project API key on an Agents API Beta route, or none supplied to Files or Skills | +| 404 | `not_found_error` | `/v1`, `/core/v1`, `/api/v1` | The resource does not exist in the caller's or the selected Project's tenant, or the Environment of a native installation no longer exists | +| 404 | `not_found` | `/core/v1` | Unknown Core operation, unknown harness, or a harness without a deployment default model provider | +| 404 | `unsupported_operation` | `/v1` | Unknown `/v1` operation | +| 404 | null | `/v1` | Missing File or Skill on the public Files and Skills routes | +| 405 | `unsupported_operation` | all | Method not allowed, including HEAD on content downloads and Runtime reads | +| 409 | `conflict_error` | `/v1`, `/core/v1` | Official conflicts: Session not idle for deletion, pending input, MCP credential ambiguity, hosted environment failure or a different tool result | +| 409 | `turn_conflict` | `/v1` | The Session or Turn cannot accept this change in its current state, such as an Environment file write while Session input is pending | +| 409 | `idempotency_conflict` | `/v1`, `/api/v1` | The Idempotency-Key was used with different input; on sandbox node enrollment, the node ID is already enrolled | +| 409 | `environment_unavailable` | `/v1` | The Environment no longer accepts new input | +| 409 | `environment_input_expired` | `/v1` | The Environment input deadline passed before admission | +| 409 | `environment_input_cancelled` | `/v1` | The Environment input was cancelled before admission | +| 409 | `project_exists` | `/core/v1` | The Project ID already exists | +| 409 | `project_api_key_exists` | `/core/v1` | The API key ID already exists; list its metadata and revoke it if the secret was not saved | +| 409 | `project_archived` | `/core/v1` | The target Project is archived | +| 409 | `executor_credential_exists` | `/core/v1`, `/api/v1` | The executor key ID already exists; rotate it explicitly to replace the secret. On the native installation claim, the Environment already has another, rotated or revoked executor credential | +| 409 | `runtime_history_unsupported` | `/core/v1` | Runtime history is not supported for this Session | +| 409 | `sandbox_deployment_conflict` | `/core/v1`, `/api/v1` | The sandbox deployment cannot change in its current state | +| 409 | `sandbox_configuration_error` | `/core/v1` | The deployment cannot be served as configured, for example E2B with a loopback public URL | +| 409 | `sandbox_node_address_mismatch` | `/core/v1`, `/api/v1` | The node uses a different Core address than the installation public URL | +| 409 | `sandbox_specification_mismatch` | `/core/v1`, `/api/v1` | The node's resource limits or Runtime release do not match the active deployment | +| 409 | `runtime_node_in_use` | `/core/v1` | The node still holds allocations, snapshots, reservations or pending cleanup | +| 409 | `runtime_local_node_configured` | `/core/v1` | The local node is enabled in deployment configuration and cannot be removed | +| 409 | `sandbox_generation_stale` | `/core/v1` | The deployment generation changed; `details.current_generation` gives the new one. Refresh before submitting again | +| 409 | `sandbox_reset_required` | `/core/v1` | The change needs a reset first, such as another backend or E2B team; `details` names both providers | +| 409 | `sandbox_in_use` | `/core/v1` | Hosted sandbox resources still belong to the deployment; `details.allocations` and `details.pending` count them | +| 409 | `sandbox_reset_in_progress` | `/core/v1`, `/api/v1` | A sandbox reset is in progress, so the deployment cannot change and nodes cannot enroll or read their configuration | +| 409 | `sandbox_not_configured` | `/core/v1` | The operation needs a configured sandbox deployment | +| 409 | `e2b_team_mismatch` | `/core/v1` | The E2B key cannot manage the retained deployment; reset before changing teams (param `e2b.api_key`) | +| 413 | `request_too_large` | all | The body exceeds the operation's limit, or an uploaded File or Skill exceeds its content limit | +| 500 | `internal_error` | all | An unexpected persistence failure; no detail is exposed | +| 503 | `authentication_unavailable` | `/v1` | Project API key authentication is temporarily unavailable; written before any operation runs | +| 503 | `execution_unavailable` | `/v1`, `/core/v1` | Execution or Core Runtime observation is not available on this service, or a Core Runtime observation list exceeded its request budget | +| 503 | `stream_unavailable` | `/v1` | Live events or streaming creation are unavailable | +| 503 | `credential_storage_unavailable` | `/v1`, `/core/v1` | Credential encryption is not configured | +| 503 | `file_storage_unavailable` | `/v1`, `/core/v1` | Source File storage is not configured | +| 503 | `file_transfer_unavailable` | `/v1`, `/core/v1` | The bounded transfer deadline cannot be set for an upload or download | +| 503 | `skill_storage_unavailable` | `/v1`, `/core/v1` | Skill storage is not configured | +| 503 | `artifact_storage_unavailable` | `/v1`, `/core/v1` | Artifact storage is not configured | +| 503 | `subagent_storage_unavailable` | `/v1` | Subagent storage is not configured | +| 503 | `execution_configuration_unavailable` | `/core/v1` | Session execution configuration cannot be read | +| 503 | `runtime_history_unavailable` | `/core/v1` | Durable Runtime history is not configured or temporarily unavailable | +| 503 | `core_metrics_unavailable` | `/core/v1` | Core metrics are not configured or could not be read | +| 503 | `runtime_node_unavailable` | `/v1`, `/core/v1`, `/api/v1` | The selected sandbox node is unavailable, or no node has capacity for a new hosted Session | +| 503 | `sandbox_credential_unavailable` | `/core/v1`, `/api/v1` | Sandbox credentials cannot be decrypted; check the service credential encryption configuration | +| 503 | `sandbox_reset_in_progress` | `/v1` | Hosted admission is paused while a sandbox reset runs; nothing was admitted | +| 503 | `sandbox_nodes_preparing` | `/v1` | The nodes with free capacity are still preparing the deployment's Runtime | +| 503 | `e2b_request_unconfirmed` | `/core/v1` | E2B verification could not be confirmed; nothing is replayed | +| 503 | `provider_unavailable` | `/core/v1` | E2B template discovery is unavailable; check the credential, endpoint and connection | +| 503 | `diagnostics_unavailable` | `/core/v1` | The Session diagnostics reader is not configured | +| 503 | `installation_unavailable` | `/api/v1` | Matching native installation artifacts are unavailable on this Core | + +The namespace column shows where each code is expected. Codes from the shared +stored-error mapping can appear on any operation whose storage reports that +condition. No 503 carries `Retry-After`. + +Core's reverse-path canonicalization answers a path that cannot be decoded with a +plain-text 400 before any namespace is selected; a parsed request path always +decodes, so this is not expected in practice. + +## Session event error codes + +These codes appear inside Session events, in a live stream that has already +answered 200 and in the saved event history. Core's own interruption is an +`event: error` frame whose `error` object has `code`, `type` and `message` but no +`param`. A hosted provisioning failure records the pinned `error` event, with a +null `param`, and the Environment state `error` of +`agent.session.environment.failed`, which has no `param`. See +[history, events and usage](history-events-usage.md). + +| Status | Code | Meaning | +| --- | --- | --- | +| 200 | `stream_interrupted` | The live stream was interrupted; reconnect, then read the Session and its saved Items to recover | +| 200 | `sandbox_error` | `error` event, type `environment_error`: the hosted Environment failed to provision; the message is a safe reason without command output | +| 200 | `environment_connection_failed` | Environment state error, type `environment_error`, in `agent.session.environment.failed` | + +## Console codes + +Web's server writes these for `/core/*` requests it rejects before forwarding, +and for the console-local `POST /console/installation/domain` HTTPS setup request. +See [Core errors](core-errors.md#console-generated-failures) and +[Web request boundaries](../../docs/web/architecture.md#request-boundaries). + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | `console_request_invalid` | Request path, method or upgrade is unsafe | +| 400 | `domain_setup_unavailable` | Domain setup: this installation uses an external reverse proxy, so HTTPS is configured there | +| 400 | `invalid_request` | Domain setup: the request body exceeds 2 KiB | +| 401 | `console_sign_in_required` | Console session is missing or expired | +| 403 | `console_origin_rejected` | Host, Origin or Fetch Metadata checks failed | +| 502 | `core_unreachable` | Core transport failed or Core tried to redirect | +| 502 | `installation_unreachable` | Domain setup: the installer did not answer or returned an invalid or 5xx response; run `oac status` on the server | + +## Installation domain setup codes + +`POST /console/installation/domain` relays these installer rejections unchanged +in `{"error":{"code":"…","message":"…"}}`. The installation controller in +`deploy/install/ingress.py` writes them; see [Web management](../../docs/api/web-management.md) +and the [installer contract](../../docs/maintainers.md#managed-https-ownership). +Failures after the `202` acceptance are reported through the status `message`, +not as codes. + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | `domain_setup_unavailable` | Managed HTTPS needs a combined Docker installation | +| 400 | `invalid_hostname` | The installer's hostname validation rejected the value | +| 400 | `invalid_confirmation` | `confirm_public_url_change` does not equal the new HTTPS URL | +| 400 | `invalid_request` | The body is missing, larger than 2 KiB, not JSON or has other members | +| 401 | `unauthorized` | The installer rejected the console's Core key | +| 409 | `configuration_pending` | `config.json` has pending edits; apply or revert them first | +| 409 | `installation_not_ready` | The installation has not been applied yet | +| 409 | `installation_not_running` | Core, Web, the gateway or the installation service is not running | +| 409 | `generated_files_edited` | Generated files were edited by hand; resolve them with `oac apply` | +| 409 | `public_url_confirmation_required` | The address changes existing bindings; resubmit with `confirm_public_url_change` | +| 409 | `installation_busy` | Another installation operation holds the lock, or the installer rejected the change | + +## Console sign-in responses + +`/console/auth`, `/console/auth/login`, `/console/auth/logout` and the other +signed-in console pages outside `/core/*` answer failures as +`{"error":""}` with no code. Clients branch on the status. + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | null | The login body is not a JSON object with only a non-empty `core_key` | +| 401 | null | Wrong Core key, or a console page requested without a session | +| 403 | null | Host, Origin or Fetch Metadata checks failed outside `/core/*` | +| 404 | null | Unknown `/console/auth/*` route | +| 405 | null | Login or logout without POST (`Allow: POST`) | +| 415 | null | The login body is not `application/json` | +| 429 | null | Sign-in is busy (`Retry-After: 1`) or ten failed attempts in one minute (`Retry-After: 60`) | +| 503 | null | A session token could not be generated | + +Outside `/core/*` the console also answers an unsafe path with a plain-text 400, +a wrong method on static pages and `/node-install/*` with a plain-text 405 +(`Allow: GET, HEAD`), and unknown or direct `/v1` and `/api/v1` paths with a +plain-text 404. After sign-in, `/core` and `/core/*` paths outside `/core/v1` +also get a plain-text 404, `/console/api-keys` and its subpaths a plain-text 404, +and `/console/installation/domain` with a method other than GET or POST a +plain-text 405 (`Allow: GET, POST`). `GET /healthz` returns `200 ok` without +authentication. + +## Runtime daemon transport codes + +`/api/v1/agent-daemon/ws`, `/bootstrap` and `/device-status` answer the failures +their handlers detect as `{"error":"","detail":""}`. `detail` is +diagnostic text, not a stable value. The router in front of them answers an +unknown `/api/v1/agent-daemon/*` path with a plain-text 404 and a wrong method with +an empty 405, and a failed WebSocket handshake on `ws` is answered as plain text by +the WebSocket library, so clients must not assume the JSON body on every +failure. + +| Status | Code | Meaning | +| --- | --- | --- | +| 400 | `missing_params` | `device_id`, `version` or the Bearer credential is missing | +| 400 | `missing_device_id` | The bootstrap body or device-status query has no `device_id` | +| 400 | `bad_json` | The bootstrap body is not valid JSON | +| 401 | `missing_bearer` | No Bearer daemon credential | +| 401 | `unknown_device` | The device is not enrolled | +| 401 | `bad_credential` | The daemon credential does not match the device | +| 403 | `wrong_runtime_type` | The credential belongs to another Runtime type | +| 405 | `method_not_allowed` | Bootstrap without POST, if the handler is reached; the router's empty 405 normally answers first | +| 426 | `incompatible_version` | The daemon version is not supported by this Core | +| 500 | `internal` | Authentication failed unexpectedly | + +## Plain-text transport responses + +These routes answer failures with a `text/plain` body and no code. + +| Status | Code | Routes | Meaning | +| --- | --- | --- | --- | +| 400 | null | `POST agent-daemon/enroll`, `GET agent-daemon/connection` | Invalid body or query | +| 401 | null | enroll, connection, `GET sandbox-node/connect` | Missing or rejected credential | +| 405 | null | enroll, connection | Wrong method (`Allow` names the method) | +| 409 | null | enroll, connection, sandbox-node/connect | The Environment is bound to another executor, or the node identity is already connected | +| 503 | null | enroll, connection, sandbox-node/connect | Enrollment storage, node authentication or the connection owner is unavailable | + +The public installer artifacts under `/api/v1/agent-daemon/install/{version}/` +answer a method other than GET or HEAD with an empty 405 and an unknown file with +a plain-text 404. + +## Client-generated codes + +`packages/agents-client` creates these `AgentCoreError` codes itself; Core never +sends them. + +Codes that report a malformed response use status 502 (or 0 for Core metrics) +and mean the client rejected what Core returned; they never indicate a request +error. + +| Code | Meaning | +| --- | --- | +| `invalid_admin_response` | An administration or sandbox administration response has the wrong shape (`AdminClient`, `SandboxAdminClient`) | +| `invalid_response` | A Core metrics response has the wrong shape (`CoreMetricsClient`) | +| `sandbox_configuration_unconfirmed` | A sandbox configuration write failed without a confirmed outcome, or its reason was withheld because it could echo the key; refresh before submitting again | +| `credential_write_failed` | A Vault credential write was rejected; the client keeps the status but never parses the body, which could reflect the secret | +| `invalid_environment_template` | An Environment Template response has the wrong shape | +| `invalid_environment_template_list` | An Environment Template list has the wrong shape | +| `invalid_vault_resource` | A Vault response has the wrong shape or another ID | +| `invalid_vault_list` | A Vault list has the wrong shape | +| `invalid_vault_deletion` | A Vault deletion receipt has the wrong shape or another ID | +| `invalid_vault_credential` | Credential metadata has the wrong shape or another ID | +| `invalid_vault_credential_list` | A Credential list has the wrong shape | +| `invalid_vault_credential_deletion` | A Credential deletion receipt has the wrong shape or another ID | +| `invalid_session_vaults` | A Session's Vault attachments have the wrong shape | +| `invalid_environment_resource` | An Environment response has the wrong shape | +| `invalid_environment_file` | An Environment file response has the wrong shape | +| `invalid_environment_files` | An Environment files page has the wrong shape | +| `invalid_session_resource` | A Session response has the wrong shape | +| `invalid_session_list` | A Session list has the wrong shape | +| `invalid_history_resource` | A Turn, Item or other history response has the wrong shape | +| `invalid_runtime_observation` | A Runtime observation has the wrong shape | +| `invalid_stream_event` | An event stream frame has the wrong shape | +| `empty_stream` | An event stream closed before its first event | +| `invalid_source_file` | Source File metadata has the wrong shape | +| `invalid_source_file_list` | A Files list has the wrong shape | +| `invalid_source_file_content` | Source File content is incomplete or has the wrong headers | +| `invalid_skill_resource` | A Skill or Skill version response has the wrong shape | +| `invalid_skill_content` | Skill content is incomplete or has the wrong headers | diff --git a/contracts/agents-api/openapi.yaml b/contracts/agents-api/openapi.yaml index f53cc5999..ff87fb80f 100644 --- a/contracts/agents-api/openapi.yaml +++ b/contracts/agents-api/openapi.yaml @@ -2223,6 +2223,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List reusable Agents @@ -2293,6 +2297,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Create a reusable Agent @@ -2342,6 +2350,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a reusable Agent @@ -2384,6 +2396,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve a reusable Agent @@ -2444,6 +2460,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Update a reusable Agent @@ -2494,6 +2514,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an execution Environment @@ -2710,6 +2734,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List Environment Templates @@ -2764,6 +2792,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Create an Environment Template @@ -2807,6 +2839,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete an Environment Template @@ -2849,6 +2885,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an Environment Template @@ -2913,6 +2953,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Update an Environment Template @@ -2978,6 +3022,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List execution Sessions @@ -3221,6 +3269,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete an execution Session @@ -3265,6 +3317,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an execution Session @@ -3325,6 +3381,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Update execution Session metadata @@ -3768,6 +3828,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List persisted execution Items @@ -4241,6 +4305,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List execution Turns @@ -4290,6 +4358,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve an execution Turn @@ -4572,6 +4644,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillList' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List Skills @@ -4596,6 +4688,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.Skill' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Upload a Skill @@ -4618,6 +4730,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillDeleted' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Skill and its versions @@ -4639,6 +4771,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.Skill' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve Skill metadata @@ -4668,6 +4820,30 @@ paths: description: OK schema: $ref: '#/definitions/v1.Skill' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Update the default Skill version @@ -4691,6 +4867,26 @@ paths: description: OK schema: type: file + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Download Skill content @@ -4735,6 +4931,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersionList' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List Skill versions @@ -4765,6 +4981,30 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersion' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Upload an immutable Skill version @@ -4793,6 +5033,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersionDeleted' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Skill version @@ -4817,6 +5077,26 @@ paths: description: OK schema: $ref: '#/definitions/v1.SkillVersion' + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve Skill version metadata @@ -4842,6 +5122,26 @@ paths: description: OK schema: type: file + "400": + description: Bad Request + schema: + $ref: '#/definitions/v1.ErrorResponse' + "401": + description: Unauthorized + schema: + $ref: '#/definitions/v1.ErrorResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/v1.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Download immutable Skill version content @@ -4920,6 +5220,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List Vaults @@ -4970,6 +5274,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Create a Vault @@ -5023,6 +5331,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Vault and all its Credentials @@ -5066,6 +5378,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve a Vault @@ -5150,6 +5466,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: List safe Vault Credential metadata @@ -5276,6 +5596,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Delete a Vault Credential @@ -5325,6 +5649,10 @@ paths: description: Internal Server Error schema: $ref: '#/definitions/v1.ErrorResponse' + "503": + description: Service Unavailable + schema: + $ref: '#/definitions/v1.ErrorResponse' security: - BearerAuth: [] summary: Retrieve safe Vault Credential metadata diff --git a/contracts/agents-api/runtime.openapi.yaml b/contracts/agents-api/runtime.openapi.yaml index 329d7fce1..d650c84dc 100644 --- a/contracts/agents-api/runtime.openapi.yaml +++ b/contracts/agents-api/runtime.openapi.yaml @@ -209,6 +209,10 @@ paths: description: Not Found schema: $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' "503": description: Service Unavailable schema: @@ -243,6 +247,14 @@ paths: description: Conflict schema: $ref: '#/definitions/api.CoreErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/api.CoreErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.CoreErrorResponse' "503": description: Service Unavailable schema: @@ -329,6 +341,10 @@ paths: description: Conflict schema: $ref: '#/definitions/v1.ErrorResponse' + "413": + description: Request Entity Too Large + schema: + $ref: '#/definitions/v1.ErrorResponse' "500": description: Internal Server Error schema: diff --git a/docs/api/README.md b/docs/api/README.md index 41f9a47f1..cb8bcc127 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -17,7 +17,8 @@ A credential used in another namespace gets 401: a Project API key on `/core/v1` **Routing.** The reverse proxy sends `/v1` and `/api/v1` to Core and everything else to Web ([proxy setup](../getting-started/install.md#https-and-the-reverse-proxy)). Browsers reach `/core/v1` only through Web's server, which adds the Core key after -sign-in; Web returns 404 for `/v1` and `/api/v1`. Operator scripts call `/core/v1` +sign-in; Web returns 404 for `/v1` and `/api/v1`, and answers an unauthenticated +`GET /healthz` liveness probe with `200 ok`. Operator scripts call `/core/v1` on Core's loopback port. Details: [Web and Core](web-management.md). ## Public API @@ -25,7 +26,8 @@ on Core's loopback port. Details: [Web and Core](web-management.md). Applications call `/v1` with a Project API key. The routes are exactly the 58 pairs in [upstream-routes.json](../../contracts/agents-api/upstream-routes.json). The [Agents API guide](public-agent-api.md) explains every resource with SDK and HTTP -examples. +examples. [Request conventions](request-conventions.md) covers the headers, JSON body +checks and list parameters every `/v1` operation shares. ## Core API @@ -90,6 +92,16 @@ the Core key or a Project API key. | `POST agent-daemon/enroll`, `GET agent-daemon/connection` | Self-hosted executor and its installer | Executor credential from `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials` | [Executor credentials](../../contracts/agents-api/environment-executor-credentials.md) | | WebSocket `GET agent-daemon/ws`, `POST agent-daemon/bootstrap`, `GET agent-daemon/device-status` | Runtime daemons | Daemon credential: Core writes one into each hosted sandbox it prepares; a self-hosted executor uses its executor credential | [Runtime enrollment](../../services/agents-api/README.md#user-managed-runtime-enrollment) | +Only the three `sandbox-node` HTTP routes and the two native installation routes +(`agent-daemon/installation` and its `/claim` subroute) are in the machine OpenAPI +and use the JSON error envelope. The node WebSocket and the daemon transport are served +beside the API router: `agent-daemon/enroll`, `agent-daemon/connection` and +`sandbox-node/connect` answer failures with a plain-text body and no code, and +`agent-daemon/ws`, `bootstrap` and `device-status` answer the failures their +handlers detect with `{"error":"","detail":"…"}`; router and WebSocket +handshake failures stay plain text. Both are listed in the +[error code registry](../../contracts/agents-api/error-codes.md#runtime-daemon-transport-codes). + ## Contract sources - [Pinned upstream baseline](../../contracts/agents-api/upstream.json): OpenAI @@ -133,3 +145,9 @@ The console-local `GET`/`POST /console/installation/domain` surface uses the sig browser session and same-origin checks. It delegates only domain setup to the installer, with the server-held Core key over a private Unix socket; it is not part of the Agents API or Core management API. See [Web request boundaries](../web/architecture.md#request-boundaries). + +Core administration failures use the [Core error envelope](../../contracts/agents-api/core-errors.md), +including typed optional safe details and distinct console proxy rejection codes. +The [error code registry](../../contracts/agents-api/error-codes.md) lists every error +code in all three namespaces, the console and the daemon transport, and is checked +against the code. diff --git a/docs/api/request-conventions.md b/docs/api/request-conventions.md new file mode 100644 index 000000000..a925c9520 --- /dev/null +++ b/docs/api/request-conventions.md @@ -0,0 +1,69 @@ +# Request conventions + +These rules apply to every `/v1` operation. An operation page adds only what that +operation does differently, and repeats a rule from above where the operation's own +description states it: the Files and Skills operations repeat the `OpenAI-Beta` rule, +and Create a reusable Agent repeats the JSON body checks. + +## Headers + +| Header | Rule | +| --- | --- | +| `Authorization` | `Bearer ` on every operation. See [API namespaces and credentials](README.md). | +| `OpenAI-Beta` | Exactly one `agents=v1` value on every operation except Files (`/files`) and Skills (`/skills`). Otherwise 400 `invalid_beta`. The pinned SDK sends it. | +| `OpenAI-Organization`, `OpenAI-Project` | Optional. If present they must be `core` and `proj_`; otherwise the request gets the same 401 as a rejected key. | +| `Idempotency-Key` | Optional on Session creation and on event submission, up to 128 bytes. A Core extension: a retry with the same key and request returns the original result, and the same key with a different request returns 409 `idempotency_conflict`. A streamed Session creation retry is the exception; see Create an execution Session. The hosted service returned distinct Sessions for repeated creation keys; its event submission behavior is not documented. | + +## JSON request bodies + +Every operation with a JSON body checks it in this order, before any field +validation or resource lookup: + +1. The `Content-Type` must be `application/json` or another `application/*+json` + type, case-insensitive, with well-formed parameters. +2. The body must fit the operation's limit: 1 MiB, or 16 MiB for Session creation and + for creating or updating an Environment Template. Environment file uploads have + their own limits. A larger body returns 413 `request_too_large` with a Core + message naming the limit. +3. The body must be valid UTF-8 and one JSON value, with no unpaired surrogate + escape and no repeated key at any depth, and its root must be an object. An empty + body or `null` is treated as `{}`. + +Failures of checks 1 and 3 return 400 `invalid_request_error` with a null `param` +and the official message. + +Updating a Skill's default version (`POST /v1/skills/{skill_id}`) is the one +exception: it reads its body without these checks, up to 64 KiB, and an unreadable +body returns 400 `invalid_request`. + +Member names match exactly; a case variant is an unknown member. Text that contains +U+0000 or cannot be stored as UTF-8 returns 400 `invalid_request_error`. This is a +limit of Core's storage, not of the official API. + +## Lists + +Lists take `after`, `limit` and `order`; the Environment files list takes `path`, +`limit` and `order` and continues with an opaque `page` token instead of `after`. `order` is `asc` or `desc`; omitting it uses the +operation's default, and an explicitly empty value is invalid. Unknown query keys +are ignored, and a supported scalar key given twice is rejected. Array parameters, +such as the Vault and Credential `status[]` filter, may repeat. + +The `limit` bounds, the default order and the fields of each error differ between +the Agents API lists, Files and Skills. Each operation page states its bounds and how +an unresolved `after` cursor fails. The +[list query record](../../contracts/agents-api/list-query-semantics.md) has the +evidence for each family. + +## Errors + +Clients branch on the HTTP status and `error.code`, never on `message`. The +[error code registry](../../contracts/agents-api/error-codes.md) lists every code. + +## Compatibility notes + +Core implements the pinned OpenAI Agents API. Where an operation page says a +behavior is not yet verified against the hosted service, Core's behavior is +documented but has not been compared with the official service. The +[coverage record](../../contracts/agents-api/README.md) and +[operation evidence](../../contracts/agents-api/operation-evidence.md) hold the +details and the request evidence. diff --git a/scripts/name-allowlist.json b/scripts/name-allowlist.json index afe14e326..abd4cc930 100644 --- a/scripts/name-allowlist.json +++ b/scripts/name-allowlist.json @@ -765,9 +765,9 @@ "reason": "Generated copy of docs/design-principles.md: These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." }, { - "path": "apps/docs/content/docs/execution-model.mdx", + "path": "apps/docs/content/docs/architecture.mdx", "regex": "including Parsar", - "reason": "Generated copy of docs/web/architecture.md: These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." + "reason": "Generated copy of docs/architecture.md: These exact phrases refer to the separate Parsar product, its ownership or historical source, not the OpenAgentCore brand." }, { "path": "apps/docs/content/docs/install.mdx", diff --git a/services/agents-api/internal/api/admin_sessions_routes.go b/services/agents-api/internal/api/admin_sessions_routes.go index 7775b4e27..d8e8f803b 100644 --- a/services/agents-api/internal/api/admin_sessions_routes.go +++ b/services/agents-api/internal/api/admin_sessions_routes.go @@ -197,7 +197,7 @@ func (h *Handler) adminGetRuntimeObservation(w http.ResponseWriter, r *http.Requ // @Param end query integer true "Exclusive Unix-second end" minimum(1) maximum(9007199254740991) // @Param max_points query integer false "Maximum points per series; defaults to the lower of 120 and the advertised service maximum" minimum(2) maximum(10000) // @Success 200 {object} v1.RuntimeHistory -// @Failure 400,401,404,409,503 {object} CoreErrorResponse +// @Failure 400,401,404,409,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/sessions/{session_id}/runtime-history [get] func (h *Handler) adminGetRuntimeHistory(w http.ResponseWriter, r *http.Request) { diff --git a/services/agents-api/internal/api/admin_skills_routes.go b/services/agents-api/internal/api/admin_skills_routes.go index 583968e5b..96b207d2a 100644 --- a/services/agents-api/internal/api/admin_skills_routes.go +++ b/services/agents-api/internal/api/admin_skills_routes.go @@ -8,9 +8,10 @@ import "net/http" // @Produce json // @Security DeploymentAdminAuth // @Param after query string false "Skill resource cursor" -// @Param limit query integer false "Page size; 0 returns an empty page" default(20) minimum(0) maximum(100) +// @Param limit query integer false "Page size, 1–100" default(20) minimum(1) maximum(100) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) // @Success 200 {object} v1.SkillList +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills [get] func (h *Handler) adminListSkills(w http.ResponseWriter, r *http.Request) { @@ -24,6 +25,7 @@ func (h *Handler) adminListSkills(w http.ResponseWriter, r *http.Request) { // @Security DeploymentAdminAuth // @Param skill_id path string true "Skill ID" // @Success 200 {object} v1.Skill +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id} [get] func (h *Handler) adminGetSkill(w http.ResponseWriter, r *http.Request) { @@ -37,6 +39,7 @@ func (h *Handler) adminGetSkill(w http.ResponseWriter, r *http.Request) { // @Security DeploymentAdminAuth // @Param skill_id path string true "Skill ID" // @Success 200 {object} v1.SkillDeleted +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id} [delete] func (h *Handler) adminDeleteSkill(w http.ResponseWriter, r *http.Request) { @@ -50,6 +53,7 @@ func (h *Handler) adminDeleteSkill(w http.ResponseWriter, r *http.Request) { // @Security DeploymentAdminAuth // @Param skill_id path string true "Skill ID" // @Success 200 {file} binary +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id}/content [get] func (h *Handler) adminSkillContent(w http.ResponseWriter, r *http.Request) { @@ -63,9 +67,10 @@ func (h *Handler) adminSkillContent(w http.ResponseWriter, r *http.Request) { // @Security DeploymentAdminAuth // @Param skill_id path string true "Skill ID" // @Param after query string false "Version resource cursor" -// @Param limit query integer false "Page size; 0 returns an empty page" default(20) minimum(0) maximum(100) +// @Param limit query integer false "Page size, 1–100" default(20) minimum(1) maximum(100) // @Param order query string false "Version order; omit for descending, explicit empty values are invalid" Enums(asc,desc) // @Success 200 {object} v1.SkillVersionList +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id}/versions [get] func (h *Handler) adminListSkillVersions(w http.ResponseWriter, r *http.Request) { @@ -80,6 +85,7 @@ func (h *Handler) adminListSkillVersions(w http.ResponseWriter, r *http.Request) // @Param skill_id path string true "Skill ID" // @Param version path string true "Concrete version number" // @Success 200 {object} v1.SkillVersion +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id}/versions/{version} [get] func (h *Handler) adminGetSkillVersion(w http.ResponseWriter, r *http.Request) { @@ -94,6 +100,7 @@ func (h *Handler) adminGetSkillVersion(w http.ResponseWriter, r *http.Request) { // @Param skill_id path string true "Skill ID" // @Param version path string true "Concrete version number" // @Success 200 {object} v1.SkillVersionDeleted +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id}/versions/{version} [delete] func (h *Handler) adminDeleteSkillVersion(w http.ResponseWriter, r *http.Request) { @@ -108,6 +115,7 @@ func (h *Handler) adminDeleteSkillVersion(w http.ResponseWriter, r *http.Request // @Param skill_id path string true "Skill ID" // @Param version path string true "Concrete version number" // @Success 200 {file} binary +// @Failure 400,401,404,500,503 {object} CoreErrorResponse // @Param project_id path string true "Project ID" // @Router /core/v1/projects/{project_id}/skills/{skill_id}/versions/{version}/content [get] func (h *Handler) adminSkillVersionContent(w http.ResponseWriter, r *http.Request) { diff --git a/services/agents-api/internal/api/agents.go b/services/agents-api/internal/api/agents.go index 77150d824..2a458b4ec 100644 --- a/services/agents-api/internal/api/agents.go +++ b/services/agents-api/internal/api/agents.go @@ -28,7 +28,7 @@ type AgentStore interface { // @Param OpenAI-Beta header string true "agents=v1" // @Param body body v1.CreateAgentRequest true "Reusable Agent configuration" // @Success 201 {object} v1.SavedAgent -// @Failure 400,401,413,500 {object} v1.ErrorResponse +// @Failure 400,401,413,500,503 {object} v1.ErrorResponse // @Router /agents [post] func (h *Handler) createAgent(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONObject(w, r) @@ -70,7 +70,7 @@ func (h *Handler) createAgent(w http.ResponseWriter, r *http.Request) { // @Param OpenAI-Beta header string true "agents=v1" // @Param agent_id path string true "Agent ID" // @Success 200 {object} v1.SavedAgent -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/{agent_id} [get] func (h *Handler) getAgent(w http.ResponseWriter, r *http.Request) { agent, err := h.lookupAgent(r.Context(), tenantID(r), chi.URLParam(r, "agent_id")) diff --git a/services/agents-api/internal/api/agents_delete.go b/services/agents-api/internal/api/agents_delete.go index 85b4d876b..e0279e9ad 100644 --- a/services/agents-api/internal/api/agents_delete.go +++ b/services/agents-api/internal/api/agents_delete.go @@ -17,7 +17,7 @@ import ( // @Param OpenAI-Beta header string true "agents=v1" // @Param agent_id path string true "Agent ID" // @Success 200 {object} v1.AgentDeleted -// @Failure 400,401,404,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /agents/{agent_id} [delete] func (h *Handler) deleteAgent(w http.ResponseWriter, r *http.Request) { body, ok := readJSONBody(w, r) diff --git a/services/agents-api/internal/api/agents_list.go b/services/agents-api/internal/api/agents_list.go index 8793d8666..8d347cd64 100644 --- a/services/agents-api/internal/api/agents_list.go +++ b/services/agents-api/internal/api/agents_list.go @@ -16,7 +16,7 @@ import ( // @Param limit query int64 false "Page size; 0 is treated as 1 and values above 100 as 100" minimum(0) default(20) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) default(desc) // @Success 200 {object} v1.SavedAgentList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents [get] func (h *Handler) listAgents(w http.ResponseWriter, r *http.Request) { options, ok := readClampedPage(w, r) diff --git a/services/agents-api/internal/api/agents_update.go b/services/agents-api/internal/api/agents_update.go index fddb61238..5a8a5448a 100644 --- a/services/agents-api/internal/api/agents_update.go +++ b/services/agents-api/internal/api/agents_update.go @@ -20,7 +20,7 @@ import ( // @Param agent_id path string true "Agent ID" // @Param body body v1.UpdateAgentRequest true "Supplied reusable Agent fields" // @Success 200 {object} v1.SavedAgent -// @Failure 400,401,404,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /agents/{agent_id} [post] func (h *Handler) updateAgent(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONObject(w, r) diff --git a/services/agents-api/internal/api/contract_conformance_test.go b/services/agents-api/internal/api/contract_conformance_test.go new file mode 100644 index 000000000..1d6f56695 --- /dev/null +++ b/services/agents-api/internal/api/contract_conformance_test.go @@ -0,0 +1,922 @@ +package api + +// These checks keep the published responses and error codes tied to the code +// that writes them. They read source only; no handler runs. See +// contracts/agents-api/error-codes.md for the registry they compare against. + +import ( + "fmt" + "go/ast" + "go/parser" + "go/token" + "os" + "path/filepath" + "regexp" + "slices" + "sort" + "strconv" + "strings" + "testing" + + "gopkg.in/yaml.v3" +) + +const conformanceRepoRoot = "../../../.." + +// statusValues maps the net/http constants this repository writes. An unknown +// constant fails the check instead of being silently ignored. +var statusValues = map[string]int{ + "StatusOK": 200, "StatusCreated": 201, "StatusAccepted": 202, "StatusNoContent": 204, + "StatusBadRequest": 400, "StatusUnauthorized": 401, "StatusForbidden": 403, "StatusNotFound": 404, + "StatusMethodNotAllowed": 405, "StatusConflict": 409, "StatusRequestEntityTooLarge": 413, + "StatusUnsupportedMediaType": 415, "StatusUpgradeRequired": 426, "StatusTooManyRequests": 429, + "StatusInternalServerError": 500, "StatusBadGateway": 502, "StatusServiceUnavailable": 503, + "StatusGatewayTimeout": 504, +} + +type sourcePackage struct { + fset *token.FileSet + files []*ast.File + funcs map[string]*ast.FuncDecl // "Name" or "Receiver.Name" +} + +func parseSourcePackage(t *testing.T, dir string) sourcePackage { + t.Helper() + fset := token.NewFileSet() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + result := sourcePackage{fset: fset, funcs: map[string]*ast.FuncDecl{}} + for _, entry := range entries { + name := entry.Name() + if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") { + continue + } + file, err := parser.ParseFile(fset, filepath.Join(dir, name), nil, parser.ParseComments) + if err != nil { + t.Fatal(err) + } + result.files = append(result.files, file) + for _, decl := range file.Decls { + if fn, ok := decl.(*ast.FuncDecl); ok { + result.funcs[funcKey(fn)] = fn + } + } + } + return result +} + +func funcKey(fn *ast.FuncDecl) string { + if fn.Recv == nil || len(fn.Recv.List) == 0 { + return fn.Name.Name + } + typ := fn.Recv.List[0].Type + if star, ok := typ.(*ast.StarExpr); ok { + typ = star.X + } + if ident, ok := typ.(*ast.Ident); ok { + return ident.Name + "." + fn.Name.Name + } + return fn.Name.Name +} + +// statusConstant returns the value of an http.StatusX selector. +func statusConstant(t *testing.T, expr ast.Expr) (int, bool) { + selector, ok := expr.(*ast.SelectorExpr) + if !ok { + return 0, false + } + pkg, ok := selector.X.(*ast.Ident) + if !ok || pkg.Name != "http" || !strings.HasPrefix(selector.Sel.Name, "Status") || selector.Sel.Name == "StatusText" { + return 0, false + } + value, known := statusValues[selector.Sel.Name] + if !known { + t.Fatalf("add http.%s to statusValues", selector.Sel.Name) + } + return value, true +} + +// errorWriters take the HTTP status as their second argument. +var errorWriters = map[string]bool{"writeError": true, "writeAPIError": true, "writeCoreError": true} + +// statusArgument reads a status argument: an http.StatusX constant or an +// integer literal in the HTTP status range, such as writeError(w, 503, ...). +func statusArgument(t *testing.T, expr ast.Expr) (int, bool) { + if status, ok := statusConstant(t, expr); ok { + return status, true + } + literal, ok := expr.(*ast.BasicLit) + if !ok || literal.Kind != token.INT { + return 0, false + } + value, err := strconv.Atoi(literal.Value) + return value, err == nil && value >= 100 && value <= 599 +} + +func stringLiteral(expr ast.Expr) (string, bool) { + literal, ok := expr.(*ast.BasicLit) + if !ok || literal.Kind != token.STRING { + return "", false + } + value, err := strconv.Unquote(literal.Value) + return value, err == nil +} + +// writtenStatuses collects the http.StatusX constants a function body uses as +// values. Comparisons and switch cases read a status rather than write one. +func writtenStatuses(t *testing.T, body ast.Node) map[int]bool { + skip := map[ast.Expr]bool{} + ast.Inspect(body, func(node ast.Node) bool { + switch n := node.(type) { + case *ast.BinaryExpr: + if n.Op == token.EQL || n.Op == token.NEQ { + skip[n.X], skip[n.Y] = true, true + } + case *ast.CaseClause: + for _, expr := range n.List { + skip[expr] = true + } + } + return true + }) + statuses := map[int]bool{} + ast.Inspect(body, func(node ast.Node) bool { + // A literal status is counted only where an error writer takes it. + if call, ok := node.(*ast.CallExpr); ok && len(call.Args) > 1 { + if ident, ok := call.Fun.(*ast.Ident); ok && errorWriters[ident.Name] { + if literal, ok := call.Args[1].(*ast.BasicLit); ok { + if status, ok := statusArgument(t, literal); ok { + statuses[status] = true + } + } + } + } + expr, ok := node.(ast.Expr) + if !ok || skip[expr] { + return true + } + if status, ok := statusConstant(t, expr); ok { + statuses[status] = true + return false + } + return true + }) + return statuses +} + +// references lists package functions and methods a function calls or passes +// as a value. Without type information a method resolves only through the +// function's own receiver or a Handler named h; w.WriteHeader on an interface +// and field calls such as h.store.Get stay unresolved. +func (p sourcePackage) references(fn *ast.FuncDecl) []string { + receivers := map[string]string{"h": "Handler"} + if fn.Recv != nil && len(fn.Recv.List) > 0 && len(fn.Recv.List[0].Names) > 0 { + if receiver, _, ok := strings.Cut(funcKey(fn), "."); ok { + receivers[fn.Recv.List[0].Names[0].Name] = receiver + } + } + var out []string + selected := map[*ast.Ident]bool{} + ast.Inspect(fn.Body, func(node ast.Node) bool { + switch n := node.(type) { + case *ast.SelectorExpr: + selected[n.Sel] = true + if ident, ok := n.X.(*ast.Ident); ok { + if receiver, ok := receivers[ident.Name]; ok { + if _, exists := p.funcs[receiver+"."+n.Sel.Name]; exists { + out = append(out, receiver+"."+n.Sel.Name) + } + } + return false + } + case *ast.Ident: + if selected[n] { + return true + } + if fn, ok := p.funcs[n.Name]; ok && fn.Recv == nil { + out = append(out, n.Name) + } + } + return true + }) + return out +} + +type operation struct { + handler, method, path string + declared map[int]bool + successes, failures int +} + +var ( + routerAnnotation = regexp.MustCompile(`^@Router\s+(\S+)\s+\[(\w+)\]`) + statusAnnotation = regexp.MustCompile(`^@(Success|Failure)\s+([0-9,]+)(\s|$)`) +) + +func annotatedOperations(p sourcePackage) []operation { + var out []operation + for key, fn := range p.funcs { + if fn.Doc == nil { + continue + } + op := operation{handler: key, declared: map[int]bool{}} + for _, comment := range fn.Doc.List { + line := strings.TrimSpace(strings.TrimPrefix(comment.Text, "//")) + if match := routerAnnotation.FindStringSubmatch(line); match != nil { + op.path, op.method = match[1], strings.ToUpper(match[2]) + } + if match := statusAnnotation.FindStringSubmatch(line); match != nil { + for _, value := range strings.Split(match[2], ",") { + status, _ := strconv.Atoi(value) + op.declared[status] = true + } + if match[1] == "Success" { + op.successes++ + } else { + op.failures++ + } + } + } + if op.path != "" { + out = append(out, op) + } + } + sort.Slice(out, func(i, j int) bool { return out[i].path+out[i].method < out[j].path+out[j].method }) + return out +} + +// storeDispatcher maps stored-error sentinels to many statuses. Which sentinel +// a store call returns is not visible statically, so an operation reaching it +// is required to declare only what every lookup can produce: 500 for an +// unknown persistence failure and, when the path names a resource, 404. Any +// status the dispatcher writes is allowed as a declaration. +const storeDispatcher = "writeStoreError" + +// middlewareStatuses are written before an operation's handler runs. Paths +// are relative to the contract base path, so /v1 operations have no prefix. +func middlewareStatuses(path string) []int { + switch { + case strings.HasPrefix(path, "/core/v1/"): + return []int{401} // invalid_admin_key + case strings.HasPrefix(path, "/api/v1/"): + return []int{401} // enrollment token or node credential + case strings.HasPrefix(path, "/files") || strings.HasPrefix(path, "/skills"): + // authenticateProject: invalid_api_key or null code; authentication_unavailable. + return []int{401, 503} + default: + // authenticate adds the OpenAI-Beta check: 400 invalid_beta. + return []int{400, 401, 503} + } +} + +// reachableStatuses maps each status a handler can write to the first function +// found writing it, so a failure names where the status comes from, and +// reports whether the handler reaches the stored-error dispatcher. +func (p sourcePackage) reachableStatuses(t *testing.T, handler string) (map[int]string, bool) { + statuses := map[int]string{} + usesStore := false + seen := map[string]bool{} + queue := []string{handler} + for len(queue) > 0 { + key := queue[0] + queue = queue[1:] + if seen[key] { + continue + } + seen[key] = true + if key == storeDispatcher { + usesStore = true + continue + } + fn := p.funcs[key] + if fn == nil || fn.Body == nil { + continue + } + for status := range writtenStatuses(t, fn.Body) { + if _, ok := statuses[status]; !ok { + statuses[status] = key + } + } + queue = append(queue, p.references(fn)...) + } + return statuses, usesStore +} + +func sortedStatuses(values map[int]bool) []int { + out := make([]int, 0, len(values)) + for value := range values { + out = append(out, value) + } + sort.Ints(out) + return out +} + +// publishedOperations counts the operations of the three generated contracts. +func publishedOperations(t *testing.T) int { + t.Helper() + count := 0 + for _, name := range []string{"openapi.yaml", "core.openapi.yaml", "runtime.openapi.yaml"} { + raw, err := os.ReadFile(filepath.Join(conformanceRepoRoot, "contracts/agents-api", name)) + if err != nil { + t.Fatal(err) + } + var document struct { + Paths map[string]map[string]any `yaml:"paths"` + } + if err := yaml.Unmarshal(raw, &document); err != nil { + t.Fatal(name, err) + } + for _, item := range document.Paths { + for method := range item { + switch method { + case "get", "put", "post", "delete", "options", "head", "patch", "trace": + count++ + } + } + } + } + return count +} + +// withoutSuccess lists operations that never succeed, with the reason. +var withoutSuccess = map[string]string{ + // Every stored File has purpose user_data, whose download returns 400 as + // the official API does; the operation exists only for route parity. + "Handler.sourceFileContent": "user_data Files cannot be downloaded", +} + +// TestAnnotatedResponsesCoverWrittenStatuses requires every published +// operation to declare a success and a failure response (G1), every status its +// handler, its own helpers or its middleware can write, and no failure status +// that none of them can write (G2). +func TestAnnotatedResponsesCoverWrittenStatuses(t *testing.T) { + p := parseSourcePackage(t, ".") + storeStatuses := writtenStatuses(t, p.funcs[storeDispatcher].Body) + operations := annotatedOperations(p) + if published := publishedOperations(t); len(operations) != published { + t.Errorf("found %d annotated operations, but the contracts publish %d; run make openapi", len(operations), published) + } + for _, op := range operations { + name := op.method + " " + op.path + " (" + op.handler + ")" + if _, exempt := withoutSuccess[op.handler]; op.successes == 0 && !exempt { + t.Errorf("%s declares no @Success response", name) + } + if op.failures == 0 { + t.Errorf("%s declares no @Failure response", name) + } + required, usesStore := p.reachableStatuses(t, op.handler) + possible := map[int]bool{} + for status := range required { + possible[status] = true + } + for _, status := range middlewareStatuses(op.path) { + possible[status] = true + if _, ok := required[status]; !ok { + required[status] = "authentication middleware" + } + } + if usesStore { + for status := range storeStatuses { + possible[status] = true + } + baseline := []int{500} + if strings.Contains(op.path, "{") { + baseline = append(baseline, 404) + } + for _, status := range baseline { + if _, ok := required[status]; !ok { + required[status] = storeDispatcher + } + } + } + var missing []string + for status, source := range required { + if !op.declared[status] { + missing = append(missing, fmt.Sprintf("%d (from %s)", status, source)) + } + } + sort.Strings(missing) + if len(missing) > 0 { + t.Errorf("%s can write %s but does not declare it (declares %v)", name, strings.Join(missing, ", "), sortedStatuses(op.declared)) + } + var impossible []int + for status := range op.declared { + if status >= 400 && !possible[status] { + impossible = append(impossible, status) + } + } + sort.Ints(impossible) + if len(impossible) > 0 { + t.Errorf("%s declares %v, which neither its handler, its helpers nor its middleware can write", name, impossible) + } + } +} + +// emittedCode is one (status, code) pair a writer call can produce. A status of +// 0 means the call passes a variable status. +type emittedCode struct { + status int + code string +} + +func (e emittedCode) String() string { + if e.code == "" { + return fmt.Sprintf("%d null", e.status) + } + return fmt.Sprintf("%d %s", e.status, e.code) +} + +// emittedCodes collects (status, code) pairs from calls to the named writers, +// whose status and code are the arguments at the given positions. A code +// passed as a local variable resolves to the string literals assigned to it in +// the same function; an empty code is the null code. +func emittedCodes(t *testing.T, p sourcePackage, writers map[string][2]int) map[emittedCode][]string { + out := map[emittedCode][]string{} + for key, fn := range p.funcs { + if fn.Body == nil { + continue + } + if _, wrapper := writers[key]; wrapper { + continue + } + assigned := map[string][]string{} + // Variables assigned from a multi-value call, such as + // status, code := mapAuthError(err), are covered by returnedCodes. + fromCall := map[string]bool{} + ast.Inspect(fn.Body, func(node ast.Node) bool { + if assign, ok := node.(*ast.AssignStmt); ok && len(assign.Rhs) == 1 && len(assign.Lhs) > 1 { + if _, call := assign.Rhs[0].(*ast.CallExpr); call { + for _, lhs := range assign.Lhs { + if ident, ok := lhs.(*ast.Ident); ok { + fromCall[ident.Name] = true + } + } + } + } + if assign, ok := node.(*ast.AssignStmt); ok && len(assign.Lhs) == len(assign.Rhs) { + for i, lhs := range assign.Lhs { + if ident, ok := lhs.(*ast.Ident); ok { + if value, ok := stringLiteral(assign.Rhs[i]); ok { + assigned[ident.Name] = append(assigned[ident.Name], value) + } + } + } + } + return true + }) + ast.Inspect(fn.Body, func(node ast.Node) bool { + call, ok := node.(*ast.CallExpr) + if !ok { + return true + } + ident, ok := call.Fun.(*ast.Ident) + if !ok { + return true + } + positions, ok := writers[ident.Name] + if !ok || len(call.Args) <= positions[1] { + return true + } + status, _ := statusArgument(t, call.Args[positions[0]]) + var codes []string + if value, ok := stringLiteral(call.Args[positions[1]]); ok { + codes = []string{value} + } else if variable, ok := call.Args[positions[1]].(*ast.Ident); ok { + codes = assigned[variable.Name] + if len(codes) == 0 && fromCall[variable.Name] { + return true + } + if len(codes) == 0 { + t.Errorf("%s: cannot resolve code variable %s", p.fset.Position(call.Pos()), variable.Name) + } + } else if field, ok := call.Args[positions[1]].(*ast.SelectorExpr); ok && field.Sel.Name == "Code" && typedVariables(fn)[identName(field.X)] != "" { + typ := typedVariables(fn)[identName(field.X)] + codes = typedCodes[typ] + if len(codes) == 0 { + t.Errorf("%s: no %s{Code: ...} literals found for %s.Code", p.fset.Position(call.Pos()), typ, identName(field.X)) + } + } else { + t.Errorf("%s: code argument is neither a literal, a local variable nor a typed error's Code", p.fset.Position(call.Pos())) + } + for _, code := range codes { + // An empty code is a null code; it is compared with the null rows. + if status == 0 { + t.Errorf("%s: code %s is written with a variable status", p.fset.Position(call.Pos()), code) + } + position := p.fset.Position(call.Pos()) + out[emittedCode{status, code}] = append(out[emittedCode{status, code}], filepath.Base(position.Filename)+":"+strconv.Itoa(position.Line)) + } + return true + }) + } + return out +} + +// typedCodes maps a validation error type to the codes its literals set. A +// writer that passes field.Code, for a variable declared as that type, can +// write any of them. Filled by collectTypedCodes before the registry check. +var typedCodes = map[string][]string{} + +// typedErrorTypes are the error types whose Code member reaches an error writer, +// with the packages that construct them. +var typedErrorTypes = map[string]string{ + "AdminValidationError": "services/agents-api/internal/store", + "ModelProviderError": "contracts/agents-api/v1", +} + +func collectTypedCodes(t *testing.T) { + for typ, dir := range typedErrorTypes { + p := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, dir)) + seen := map[string]bool{} + for _, file := range p.files { + ast.Inspect(file, func(node ast.Node) bool { + literal, ok := node.(*ast.CompositeLit) + if !ok || identName(literal.Type) != typ { + return true + } + for _, element := range literal.Elts { + if pair, ok := element.(*ast.KeyValueExpr); ok && identName(pair.Key) == "Code" { + code, ok := stringLiteral(pair.Value) + if !ok { + t.Errorf("%s: %s.Code is not a string literal", p.fset.Position(pair.Pos()), typ) + } else if !seen[code] { + seen[code] = true + typedCodes[typ] = append(typedCodes[typ], code) + } + } + } + return true + }) + } + if len(typedCodes[typ]) == 0 { + t.Fatalf("no %s literals in %s", typ, dir) + } + } +} + +// identName is the name of an identifier or the selected name of pkg.Name. +func identName(expr ast.Expr) string { + switch e := expr.(type) { + case *ast.Ident: + return e.Name + case *ast.SelectorExpr: + return e.Sel.Name + case *ast.StarExpr: + return identName(e.X) + } + return "" +} + +// typedVariables maps variables declared as `var name *T` or `var name T` in a +// function to T, for the typed error types above. +func typedVariables(fn *ast.FuncDecl) map[string]string { + out := map[string]string{} + ast.Inspect(fn.Body, func(node ast.Node) bool { + spec, ok := node.(*ast.ValueSpec) + if !ok || spec.Type == nil { + return true + } + if typ := identName(spec.Type); typedErrorTypes[typ] != "" { + for _, name := range spec.Names { + out[name.Name] = typ + } + } + return true + }) + return out +} + +// returnedCodes collects functions that return (http.StatusX, "code"). +func returnedCodes(t *testing.T, p sourcePackage, out map[emittedCode][]string) { + for _, fn := range p.funcs { + if fn.Body == nil { + continue + } + ast.Inspect(fn.Body, func(node ast.Node) bool { + ret, ok := node.(*ast.ReturnStmt) + if !ok || len(ret.Results) != 2 { + return true + } + status, ok := statusConstant(t, ret.Results[0]) + code, isString := stringLiteral(ret.Results[1]) + if ok && isString { + position := p.fset.Position(ret.Pos()) + out[emittedCode{status, code}] = append(out[emittedCode{status, code}], filepath.Base(position.Filename)+":"+strconv.Itoa(position.Line)) + } + return true + }) + } +} + +// streamErrorCodes collects v1.StreamError{Code: "..."} literals: error objects +// inside Session events, whose response status is already 200. +func streamErrorCodes(p sourcePackage) map[emittedCode][]string { + out := map[emittedCode][]string{} + for _, file := range p.files { + ast.Inspect(file, func(node ast.Node) bool { + literal, ok := node.(*ast.CompositeLit) + if !ok { + return true + } + selector, ok := literal.Type.(*ast.SelectorExpr) + if !ok || selector.Sel.Name != "StreamError" { + return true + } + for _, element := range literal.Elts { + if pair, ok := element.(*ast.KeyValueExpr); ok { + if key, ok := pair.Key.(*ast.Ident); ok && key.Name == "Code" { + if code, ok := stringLiteral(pair.Value); ok { + position := p.fset.Position(pair.Pos()) + out[emittedCode{200, code}] = append(out[emittedCode{200, code}], filepath.Base(position.Filename)+":"+strconv.Itoa(position.Line)) + } + } + } + } + return true + }) + } + return out +} + +// registrySection returns the (status, code) rows of one registry section. Rows +// look like "| 409 | `project_exists` | ... |"; the code cell may be null. +func registrySection(t *testing.T, heading string) map[emittedCode]bool { + t.Helper() + raw, err := os.ReadFile(filepath.Join(conformanceRepoRoot, "contracts/agents-api/error-codes.md")) + if err != nil { + t.Fatal(err) + } + row := regexp.MustCompile("^\\| *([0-9]{3}) *\\| *(`[a-z0-9_]+`|null) *\\|") + rows := map[emittedCode]bool{} + inside, found := false, false + for _, line := range strings.Split(string(raw), "\n") { + if strings.HasPrefix(line, "## ") { + inside = strings.TrimSpace(strings.TrimPrefix(line, "## ")) == heading + found = found || inside + continue + } + if !inside { + continue + } + if match := row.FindStringSubmatch(line); match != nil { + status, _ := strconv.Atoi(match[1]) + code := strings.Trim(match[2], "`") + if code == "null" { + code = "" + } + if rows[emittedCode{status, code}] { + t.Errorf("error-codes.md %q lists %d %s twice", heading, status, code) + } + rows[emittedCode{status, code}] = true + } + } + if !found { + t.Fatalf("error-codes.md has no section %q", heading) + } + return rows +} + +func compareRegistry(t *testing.T, heading string, emitted map[emittedCode][]string) { + t.Helper() + listed := registrySection(t, heading) + var undocumented, unused []string + for pair, sites := range emitted { + if !listed[pair] { + slices.Sort(sites) + undocumented = append(undocumented, pair.String()+" at "+strings.Join(sites, ", ")) + } + } + for pair := range listed { + if _, ok := emitted[pair]; !ok { + unused = append(unused, pair.String()) + } + } + sort.Strings(undocumented) + sort.Strings(unused) + for _, entry := range undocumented { + t.Errorf("%s: emitted but not listed in error-codes.md: %s", heading, entry) + } + for _, entry := range unused { + t.Errorf("%s: listed in error-codes.md but never emitted: %s", heading, entry) + } +} + +// callStatuses collects the http.StatusX argument at index of every call to +// name, which is a local function or variable, or "http.Error". +func callStatuses(t *testing.T, p sourcePackage, name string, index int) map[int]bool { + out := map[int]bool{} + for _, file := range p.files { + ast.Inspect(file, func(node ast.Node) bool { + call, ok := node.(*ast.CallExpr) + if !ok || len(call.Args) <= index { + return true + } + called := "" + switch fun := call.Fun.(type) { + case *ast.Ident: + called = fun.Name + case *ast.SelectorExpr: + if pkg, ok := fun.X.(*ast.Ident); ok { + called = pkg.Name + "." + fun.Sel.Name + } + } + if called == name { + if status, ok := statusConstant(t, call.Args[index]); ok { + out[status] = true + } + } + return true + }) + } + return out +} + +// registryStatuses returns the statuses of every row in one registry section, +// including rows whose code is null. +func registryStatuses(t *testing.T, heading string) map[int]bool { + t.Helper() + raw, err := os.ReadFile(filepath.Join(conformanceRepoRoot, "contracts/agents-api/error-codes.md")) + if err != nil { + t.Fatal(err) + } + row := regexp.MustCompile(`^\| *([0-9]{3}) *\|`) + out := map[int]bool{} + inside := false + for _, line := range strings.Split(string(raw), "\n") { + if strings.HasPrefix(line, "## ") { + inside = strings.TrimSpace(strings.TrimPrefix(line, "## ")) == heading + continue + } + if match := row.FindStringSubmatch(line); inside && match != nil { + status, _ := strconv.Atoi(match[1]) + out[status] = true + } + } + return out +} + +// TestUncodedResponsesMatchRegistry covers responses without a code: the +// console sign-in errors and the plain-text machine transport errors. +func TestUncodedResponsesMatchRegistry(t *testing.T) { + console := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, "services/core-console")) + signIn := callStatuses(t, console, "authError", 1) + if got, want := sortedStatuses(registryStatuses(t, "Console sign-in responses")), sortedStatuses(signIn); !slices.Equal(got, want) { + t.Errorf("Console sign-in responses list %v; authError writes %v", got, want) + } + transport := map[int]bool{} + enrollment := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, "services/agents-api/internal/runtimeenrollment")) + for status := range callStatuses(t, enrollment, "fail", 0) { + transport[status] = true + } + node := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, "services/agents-api/internal/sandbox/node")) + for status := range callStatuses(t, node, "http.Error", 2) { + transport[status] = true + } + if got, want := sortedStatuses(registryStatuses(t, "Plain-text transport responses")), sortedStatuses(transport); !slices.Equal(got, want) { + t.Errorf("Plain-text transport responses list %v; the handlers write %v", got, want) + } +} + +// TestErrorCodeRegistryMatchesEmittedCodes keeps the error code registry and +// the service's (status, code) pairs equal in both directions (G3). +func TestErrorCodeRegistryMatchesEmittedCodes(t *testing.T) { + collectTypedCodes(t) + // A code assigned from a helper's (status, code) result is skipped at the + // writer call, so returnedCodes must run on every package. + api := parseSourcePackage(t, ".") + codes := emittedCodes(t, api, map[string][2]int{ + "writeError": {1, 2}, "writeAPIError": {1, 2}, "writeCoreError": {1, 2}, + }) + returnedCodes(t, api, codes) + compareRegistry(t, "HTTP API codes", codes) + + console := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, "services/core-console")) + consoleCodes := emittedCodes(t, console, map[string][2]int{"consoleCoreError": {1, 2}}) + returnedCodes(t, console, consoleCodes) + compareRegistry(t, "Console codes", consoleCodes) + + // The stream writes its own interruption; the store records the error objects + // of saved Session events. + events := streamErrorCodes(api) + store := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, "services/agents-api/internal/store")) + for code, sites := range streamErrorCodes(store) { + events[code] = append(events[code], sites...) + } + compareRegistry(t, "Session event error codes", events) + + gateway := parseSourcePackage(t, filepath.Join(conformanceRepoRoot, "internal/agentdaemon/gateway")) + daemon := emittedCodes(t, gateway, map[string][2]int{"writeAuthError": {1, 2}}) + returnedCodes(t, gateway, daemon) + compareRegistry(t, "Runtime daemon transport codes", daemon) +} + +// TestInstallationDomainCodesMatchRegistry keeps the relayed installer +// rejections equal to the codes deploy/install/ingress.py answers with before +// it accepts a domain request. verify and execute run after the 202, so their +// codes reach the caller only as the status message. +func TestInstallationDomainCodesMatchRegistry(t *testing.T) { + const source = "deploy/install/ingress.py" + raw, err := os.ReadFile(filepath.Join(conformanceRepoRoot, source)) + if err != nil { + t.Fatal(err) + } + text := string(raw) + definition := regexp.MustCompile(`(?m)^def (\w+)\(`) + enclosing := func(offset int) string { + name := "" + for _, match := range definition.FindAllStringSubmatchIndex(text[:offset], -1) { + name = text[match[2]:match[3]] + } + return name + } + line := func(offset int) string { return source + ":" + strconv.Itoa(strings.Count(text[:offset], "\n")+1) } + emitted := map[emittedCode][]string{} + add := func(status int, code string, offset int) { + key := emittedCode{status, code} + emitted[key] = append(emitted[key], line(offset)) + } + raised := regexp.MustCompile(`DomainError\("(\w+)", (?:"(?:[^"\\]|\\.)*"|[\w.()]+)(?:, (\d{3}))?\)`) + for _, match := range raised.FindAllStringSubmatchIndex(text, -1) { + if name := enclosing(match[0]); name == "verify" || name == "execute" { + continue + } + status := 400 + if match[4] >= 0 { + status, _ = strconv.Atoi(text[match[4]:match[5]]) + } + add(status, text[match[2]:match[3]], match[0]) + } + replied := regexp.MustCompile(`self\.reply\((\d{3}), \{"error": \{"code": "(\w+)"`) + for _, match := range replied.FindAllStringSubmatchIndex(text, -1) { + status, _ := strconv.Atoi(text[match[2]:match[3]]) + add(status, text[match[4]:match[5]], match[0]) + } + // The handler's fallback maps an installer error and invalid JSON to fixed pairs. + codes := regexp.MustCompile(`"(\w+)" if isinstance\(error, oac_cli\.OacError\) else "(\w+)"`).FindStringSubmatchIndex(text) + statuses := regexp.MustCompile(`(\d{3}) if isinstance\(error, oac_cli\.OacError\) else (\d{3})`).FindStringSubmatch(text) + if codes == nil || statuses == nil { + t.Fatalf("%s: the request handler's fallback error mapping changed; update this test", source) + } + busy, _ := strconv.Atoi(statuses[1]) + invalid, _ := strconv.Atoi(statuses[2]) + add(busy, text[codes[2]:codes[3]], codes[0]) + add(invalid, text[codes[4]:codes[5]], codes[0]) + compareRegistry(t, "Installation domain setup codes", emitted) +} + +// TestErrorCodeRegistryNamespacesAreValid reads the Namespaces column, which no +// other check touches. Reachability is not derived: a code emitted through the +// store dispatcher cannot be attributed to a namespace statically, so only the +// cell's form is checked. A token that is not a namespace, an empty cell or a +// row claiming both "all" and a single namespace is always wrong. +func TestErrorCodeRegistryNamespacesAreValid(t *testing.T) { + raw, err := os.ReadFile(filepath.Join(conformanceRepoRoot, "contracts/agents-api/error-codes.md")) + if err != nil { + t.Fatal(err) + } + row := regexp.MustCompile("^\\| *([0-9]{3}) *\\| *(`[a-z0-9_]+`|null) *\\| *([^|]*?) *\\|") + valid := map[string]bool{"all": true, "/v1": true, "/core/v1": true, "/api/v1": true} + inside, found, rows := false, false, 0 + for _, line := range strings.Split(string(raw), "\n") { + if strings.HasPrefix(line, "## ") { + inside = strings.TrimSpace(strings.TrimPrefix(line, "## ")) == "HTTP API codes" + found = found || inside + continue + } + if !inside { + continue + } + match := row.FindStringSubmatch(line) + if match == nil { + continue + } + rows++ + where := match[1] + " " + match[2] + var tokens []string + for _, token := range strings.Split(match[3], ",") { + token = strings.Trim(strings.TrimSpace(token), "`") + if token == "" { + t.Errorf("HTTP API codes: %s has an empty namespace", where) + continue + } + if !valid[token] { + t.Errorf("HTTP API codes: %s names %q, which is not a namespace", where, token) + } + tokens = append(tokens, token) + } + if len(tokens) == 0 { + t.Errorf("HTTP API codes: %s names no namespace", where) + } + if len(tokens) > 1 && valid[tokens[0]] && tokens[0] == "all" { + t.Errorf("HTTP API codes: %s claims both \"all\" and %s", where, strings.Join(tokens[1:], ", ")) + } + } + if !found { + t.Fatal("error-codes.md has no section \"HTTP API codes\"") + } + if rows == 0 { + t.Fatal("error-codes.md HTTP API codes has no rows with a Namespaces cell") + } +} diff --git a/services/agents-api/internal/api/core_resource_errors_test.go b/services/agents-api/internal/api/core_resource_errors_test.go new file mode 100644 index 000000000..4be34548c --- /dev/null +++ b/services/agents-api/internal/api/core_resource_errors_test.go @@ -0,0 +1,98 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store" +) + +// errorProbeFiles reports every File as missing and lists nothing. +type errorProbeFiles struct{ SourceFileStore } + +func (errorProbeFiles) GetSourceFile(context.Context, string, string) (store.SourceFile, error) { + return store.SourceFile{}, store.ErrNotFound +} +func (errorProbeFiles) ListSourceFiles(context.Context, string, string, int, bool, *string) (store.SourceFilePage, error) { + return store.SourceFilePage{}, nil +} + +// errorProbeSkills reports every Skill as missing, rejects every Skill version +// cursor and refuses every version deletion as the default version. +type errorProbeSkills struct{ SkillStore } + +func (errorProbeSkills) GetSkill(context.Context, string, string) (store.Skill, error) { + return store.Skill{}, store.ErrNotFound +} +func (errorProbeSkills) ListSkills(context.Context, string, string, int, bool) (store.SkillPage, error) { + return store.SkillPage{}, nil +} +func (errorProbeSkills) ListSkillVersions(_ context.Context, _, _, after string, _ int, _ bool) (store.SkillVersionPage, error) { + if after != "" { + return store.SkillVersionPage{}, &store.InvalidCursorError{Message: "cursor"} + } + return store.SkillVersionPage{}, nil +} +func (errorProbeSkills) DeleteSkillVersion(context.Context, string, string, string) (store.SkillVersion, error) { + return store.SkillVersion{}, store.ErrDefaultSkillVersion +} + +// The Files and Skills error family is chosen by request path. Through the +// real routes, Core gets the Agents API Beta fields from the shared list +// parser and not-found mapping, while errors a handler writes itself keep their +// public fields. admin-api.md documents both; these cases keep it true. +func TestCoreFilesAndSkillsUseTheBetaErrorFamily(t *testing.T) { + h, _, _ := adminTestHandler(t, WithSourceFiles(errorProbeFiles{}), WithSkills(errorProbeSkills{})) + type result struct { + status int + code, param any + } + request := func(t *testing.T, method, path, key string) result { + t.Helper() + r := httptest.NewRequest(method, path, nil) + r.Header.Set("Authorization", "Bearer "+key) + w := httptest.NewRecorder() + h.ServeHTTP(w, r) + if w.Code == http.StatusOK { + return result{status: w.Code} + } + var body struct { + Error struct { + Code any `json:"code"` + Param any `json:"param"` + } `json:"error"` + } + if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil { + t.Fatalf("%s %s: %d %s", method, path, w.Code, w.Body.String()) + } + return result{w.Code, body.Error.Code, body.Error.Param} + } + beta := result{400, "invalid_request_error", nil} + for _, test := range []struct { + name, method, path string + public, core result + }{ + {"missing File", http.MethodGet, "/files/file-1", result{404, nil, "id"}, result{404, "not_found_error", "id"}}, + {"missing Skill", http.MethodGet, "/skills/skill-1", result{404, nil, nil}, result{404, "not_found_error", nil}}, + {"unresolved Skill version cursor", http.MethodGet, "/skills/skill-1/versions?after=skillver_x", result{400, "invalid_value", "after"}, beta}, + {"repeated Files limit", http.MethodGet, "/files?limit=1&limit=2", result{400, "unsupported_parameter", nil}, beta}, + {"repeated Skills limit", http.MethodGet, "/skills?limit=1&limit=2", result{400, "duplicate_parameter", "limit"}, beta}, + {"invalid Files order", http.MethodGet, "/files?order=sideways", result{400, nil, nil}, beta}, + {"invalid Skills order", http.MethodGet, "/skills?order=sideways", result{400, "invalid_value", "order"}, beta}, + {"Files limit 0", http.MethodGet, "/files?limit=0", result{400, nil, nil}, beta}, + {"Skills limit 0", http.MethodGet, "/skills?limit=0", result{status: 200}, beta}, + {"Skills limit above maximum", http.MethodGet, "/skills?limit=101", result{400, "integer_above_max_value", "limit"}, beta}, + {"unknown Files purpose", http.MethodGet, "/files?purpose=bogus", result{400, nil, "purpose"}, result{400, nil, "purpose"}}, + {"default Skill version deletion", http.MethodDelete, "/skills/skill-1/versions/1", result{400, "invalid_value", "version"}, result{400, "invalid_value", "version"}}, + } { + if got := request(t, test.method, "/v1"+test.path, "caller"); got != test.public { + t.Errorf("%s on /v1: got %+v, want %+v", test.name, got, test.public) + } + if got := request(t, test.method, "/core/v1/projects/"+managementProjectID+test.path, "admin"); got != test.core { + t.Errorf("%s on /core/v1: got %+v, want %+v", test.name, got, test.core) + } + } +} diff --git a/services/agents-api/internal/api/credentials.go b/services/agents-api/internal/api/credentials.go index 068d9d6c4..8adfc5c35 100644 --- a/services/agents-api/internal/api/credentials.go +++ b/services/agents-api/internal/api/credentials.go @@ -88,7 +88,7 @@ func (h *Handler) createCredential(w http.ResponseWriter, r *http.Request) { // @Param vault_id path string true "Vault ID" // @Param credential_id path string true "Credential ID" // @Success 200 {object} v1.Credential -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /vaults/{vault_id}/credentials/{credential_id} [get] func (h *Handler) getCredential(w http.ResponseWriter, r *http.Request) { vaultID, ok := credentialResourceID(w, r, "vault_id") diff --git a/services/agents-api/internal/api/credentials_delete.go b/services/agents-api/internal/api/credentials_delete.go index 1981a78bc..10c8d7ec7 100644 --- a/services/agents-api/internal/api/credentials_delete.go +++ b/services/agents-api/internal/api/credentials_delete.go @@ -16,7 +16,7 @@ import ( // @Param vault_id path string true "Vault ID" // @Param credential_id path string true "Credential ID" // @Success 200 {object} v1.CredentialDeleted -// @Failure 400,401,404,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /vaults/{vault_id}/credentials/{credential_id} [delete] func (h *Handler) deleteCredential(w http.ResponseWriter, r *http.Request) { body, ok := readJSONBody(w, r) diff --git a/services/agents-api/internal/api/credentials_list.go b/services/agents-api/internal/api/credentials_list.go index 5619cc432..864a22151 100644 --- a/services/agents-api/internal/api/credentials_list.go +++ b/services/agents-api/internal/api/credentials_list.go @@ -19,7 +19,7 @@ import ( // @Param status query string false "Scalar status filter" Enums(active,archived) // @Param status[] query []string false "Array status filter; combined with status as a union" collectionFormat(multi) Enums(active,archived) // @Success 200 {object} v1.CredentialList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /vaults/{vault_id}/credentials [get] func (h *Handler) listCredentials(w http.ResponseWriter, r *http.Request) { vaultID := credentialPathID(r, "vault_id") diff --git a/services/agents-api/internal/api/environment_executor_management.go b/services/agents-api/internal/api/environment_executor_management.go index c41b1de85..ee7f94aa6 100644 --- a/services/agents-api/internal/api/environment_executor_management.go +++ b/services/agents-api/internal/api/environment_executor_management.go @@ -112,7 +112,7 @@ func (h *Handler) listExecutorCredentials(w http.ResponseWriter, r *http.Request // @Param environment_id path string true "Environment UUID" // @Param body body api.EnvironmentExecutorCredentialRequest true "Request" // @Success 201 {object} store.IssuedExecutorCredential -// @Failure 400,401,404,409,500 {object} CoreErrorResponse +// @Failure 400,401,404,409,413,500 {object} CoreErrorResponse // @Router /core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials [post] func (h *Handler) issueExecutorCredential(w http.ResponseWriter, r *http.Request, s EnvironmentExecutorStore) { // Check order: request body (400), target (404), archived Project (409), diff --git a/services/agents-api/internal/api/environment_installation.go b/services/agents-api/internal/api/environment_installation.go index 27d2d1666..a36d31097 100644 --- a/services/agents-api/internal/api/environment_installation.go +++ b/services/agents-api/internal/api/environment_installation.go @@ -91,7 +91,7 @@ func (h *Handler) installationAuthorization(w http.ResponseWriter, r *http.Reque // @Tags Native Installation // @Produce json // @Success 200 {object} v1.NativeInstallationContext -// @Failure 401,404,503 {object} CoreErrorResponse +// @Failure 401,404,500,503 {object} CoreErrorResponse // @Router /api/v1/agent-daemon/installation [post] func (h *Handler) prepareNativeInstallation(w http.ResponseWriter, r *http.Request) { _, claim, _, ok := h.installationAuthorization(w, r) @@ -126,7 +126,7 @@ type NativeInstallationClaim struct { // @Accept json // @Param body body api.NativeInstallationClaim true "Locally persisted executor secret" // @Success 204 -// @Failure 400,401,409,503 {object} CoreErrorResponse +// @Failure 400,401,409,413,500,503 {object} CoreErrorResponse // @Router /api/v1/agent-daemon/installation/claim [post] func (h *Handler) claimNativeInstallation(w http.ResponseWriter, r *http.Request) { s, _, token, ok := h.installationAuthorization(w, r) @@ -156,7 +156,7 @@ func (h *Handler) claimNativeInstallation(w http.ResponseWriter, r *http.Request // @Param project_id path string true "Project UUID" // @Param environment_id path string true "Environment UUID" // @Success 200 {object} v1.EnvironmentInstallation -// @Failure 401,404,409 {object} CoreErrorResponse +// @Failure 401,404,409,500 {object} CoreErrorResponse // @Router /core/v1/projects/{project_id}/environments/{environment_id}/installation [get] func (h *Handler) getEnvironmentInstallation(w http.ResponseWriter, r *http.Request) { binding, ok := h.adminProjectScope(w, r) diff --git a/services/agents-api/internal/api/environment_templates.go b/services/agents-api/internal/api/environment_templates.go index 105019546..6077922af 100644 --- a/services/agents-api/internal/api/environment_templates.go +++ b/services/agents-api/internal/api/environment_templates.go @@ -94,7 +94,7 @@ func readTemplateInput(w http.ResponseWriter, r *http.Request) (store.Environmen // @Param OpenAI-Beta header string true "agents=v1" // @Param body body v1.EnvironmentTemplateRequest true "Reusable configuration" // @Success 201 {object} v1.EnvironmentTemplate -// @Failure 400,401,413,500 {object} v1.ErrorResponse +// @Failure 400,401,413,500,503 {object} v1.ErrorResponse // @Router /agents/environments/templates [post] func (h *Handler) createEnvironmentTemplate(w http.ResponseWriter, r *http.Request) { in, ok := readTemplateInput(w, r) @@ -117,7 +117,7 @@ func (h *Handler) createEnvironmentTemplate(w http.ResponseWriter, r *http.Reque // @Param OpenAI-Beta header string true "agents=v1" // @Param environment_template_id path string true "Template ID" // @Success 200 {object} v1.EnvironmentTemplate -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/environments/templates/{environment_template_id} [get] func (h *Handler) getEnvironmentTemplate(w http.ResponseWriter, r *http.Request) { value, err := h.store.GetEnvironmentTemplate(r.Context(), tenantID(r), chi.URLParam(r, "environment_template_id")) @@ -138,7 +138,7 @@ func (h *Handler) getEnvironmentTemplate(w http.ResponseWriter, r *http.Request) // @Param environment_template_id path string true "Template ID" // @Param body body v1.EnvironmentTemplateRequest true "Configuration replacements" // @Success 200 {object} v1.EnvironmentTemplate -// @Failure 400,401,404,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /agents/environments/templates/{environment_template_id} [post] func (h *Handler) updateEnvironmentTemplate(w http.ResponseWriter, r *http.Request) { in, ok := readTemplateInput(w, r) @@ -161,7 +161,7 @@ func (h *Handler) updateEnvironmentTemplate(w http.ResponseWriter, r *http.Reque // @Param OpenAI-Beta header string true "agents=v1" // @Param environment_template_id path string true "Template ID" // @Success 200 {object} v1.EnvironmentTemplateDeleted -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/environments/templates/{environment_template_id} [delete] func (h *Handler) deleteEnvironmentTemplate(w http.ResponseWriter, r *http.Request) { id, err := h.store.DeleteEnvironmentTemplate(r.Context(), tenantID(r), chi.URLParam(r, "environment_template_id")) @@ -182,7 +182,7 @@ func (h *Handler) deleteEnvironmentTemplate(w http.ResponseWriter, r *http.Reque // @Param limit query integer false "Page size; 0 is treated as 1 and values above 100 as 100" default(20) minimum(0) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) default(desc) // @Success 200 {object} v1.EnvironmentTemplateList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/environments/templates [get] func (h *Handler) listEnvironmentTemplates(w http.ResponseWriter, r *http.Request) { options, ok := readClampedPage(w, r) diff --git a/services/agents-api/internal/api/environments.go b/services/agents-api/internal/api/environments.go index e80c918bf..4d6bae9f2 100644 --- a/services/agents-api/internal/api/environments.go +++ b/services/agents-api/internal/api/environments.go @@ -18,7 +18,7 @@ import ( // @Param OpenAI-Beta header string true "agents=v1" // @Param environment_id path string true "Environment ID" // @Success 200 {object} v1.EnvironmentInfo -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/environments/{environment_id} [get] func (h *Handler) getEnvironment(w http.ResponseWriter, r *http.Request) { environment, err := h.store.GetEnvironment(r.Context(), tenantID(r), chi.URLParam(r, "environment_id")) diff --git a/services/agents-api/internal/api/handler.go b/services/agents-api/internal/api/handler.go index dc3c51a26..d01561a4d 100644 --- a/services/agents-api/internal/api/handler.go +++ b/services/agents-api/internal/api/handler.go @@ -330,7 +330,7 @@ func (h *Handler) createSession(w http.ResponseWriter, r *http.Request) { // @Param OpenAI-Beta header string true "agents=v1" // @Param session_id path string true "Session ID" // @Success 200 {object} v1.Session -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/sessions/{session_id} [get] func (h *Handler) getSession(w http.ResponseWriter, r *http.Request) { session, err := h.store.GetSession(r.Context(), tenantID(r), chi.URLParam(r, "session_id")) @@ -369,7 +369,7 @@ func (h *Handler) respondSessionStatus(w http.ResponseWriter, r *http.Request, s // @Param limit query int false "Page size; 0 is treated as 1 and values above 100 as 100" minimum(0) default(20) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) default(desc) // @Success 200 {object} v1.SessionList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/sessions [get] func (h *Handler) listSessions(w http.ResponseWriter, r *http.Request) { options, ok := readClampedPage(w, r, "agent_id") diff --git a/services/agents-api/internal/api/harness_model_providers.go b/services/agents-api/internal/api/harness_model_providers.go index 51c132287..100c84f23 100644 --- a/services/agents-api/internal/api/harness_model_providers.go +++ b/services/agents-api/internal/api/harness_model_providers.go @@ -163,7 +163,7 @@ func requiredModelProviderShape() shape { // @Produce json // @Security DeploymentAdminAuth // @Param harness path string true "Harness" -// @Param body body v1.ModelConfigurationInput true "Complete model provider bundle" +// @Param body body v1.ModelConfigurationInput true "Complete model configuration" // @Success 200 {object} api.HarnessModelConfiguration // @Failure 400,401,404,413,500,503 {object} CoreErrorResponse // @Router /core/v1/harnesses/{harness}/model-configuration [put] diff --git a/services/agents-api/internal/api/items.go b/services/agents-api/internal/api/items.go index 119ad16a0..cd678dc6f 100644 --- a/services/agents-api/internal/api/items.go +++ b/services/agents-api/internal/api/items.go @@ -16,7 +16,7 @@ import ( // @Param limit query int false "Page size; 0 is treated as 1 and values above 100 as 100" minimum(0) default(20) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) default(desc) // @Success 200 {object} v1.ItemList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/sessions/{session_id}/items [get] func (h *Handler) listItems(w http.ResponseWriter, r *http.Request) { options, ok := readClampedPage(w, r) diff --git a/services/agents-api/internal/api/project_api_keys.go b/services/agents-api/internal/api/project_api_keys.go index 84b329876..82d958f4b 100644 --- a/services/agents-api/internal/api/project_api_keys.go +++ b/services/agents-api/internal/api/project_api_keys.go @@ -131,7 +131,7 @@ func (h *Handler) listProjects(w http.ResponseWriter, r *http.Request) { // @Security DeploymentAdminAuth // @Param body body api.ProjectRequest true "Project display name" // @Success 201 {object} store.Project -// @Failure 400,401,409,500 {object} CoreErrorResponse +// @Failure 400,401,409,413,500 {object} CoreErrorResponse // @Router /core/v1/projects [post] func (h *Handler) createProject(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONBodyLimit(w, r, 4096, "Project request is too large.") @@ -161,7 +161,7 @@ func (h *Handler) createProject(w http.ResponseWriter, r *http.Request) { // @Param project_id path string true "Project UUID" // @Param body body api.ProjectRequest true "Project display name" // @Success 200 {object} store.Project -// @Failure 400,401,404,409,500 {object} CoreErrorResponse +// @Failure 400,401,404,409,413,500 {object} CoreErrorResponse // @Router /core/v1/projects/{project_id} [post] func (h *Handler) renameProject(w http.ResponseWriter, r *http.Request) { binding, ok := h.adminProjectScope(w, r) @@ -243,7 +243,7 @@ func (h *Handler) listProjectAPIKeys(w http.ResponseWriter, r *http.Request) { // @Param project_id path string true "Project UUID" // @Param body body api.ProjectAPIKeyRequest true "Key display name" // @Success 201 {object} store.IssuedProjectAPIKey -// @Failure 400,401,404,409,500 {object} CoreErrorResponse +// @Failure 400,401,404,409,413,500 {object} CoreErrorResponse // @Router /core/v1/projects/{project_id}/keys [post] func (h *Handler) createProjectAPIKey(w http.ResponseWriter, r *http.Request) { binding, ok := h.adminProjectScope(w, r) diff --git a/services/agents-api/internal/api/sandbox_deployment_setup.go b/services/agents-api/internal/api/sandbox_deployment_setup.go index 5c06a104b..00671ccb2 100644 --- a/services/agents-api/internal/api/sandbox_deployment_setup.go +++ b/services/agents-api/internal/api/sandbox_deployment_setup.go @@ -80,7 +80,7 @@ func WithSandboxDeploymentChanges( // @Accept json // @Param body body api.SandboxDeploymentInput true "Deployment selection" // @Success 200 {object} store.RuntimeDeploymentView -// @Failure 400,401,409,500,503 {object} CoreErrorResponse +// @Failure 400,401,409,413,500,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/deployment [post] func (h *Handler) initializeSandboxDeployment(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONBody(w, r) @@ -115,7 +115,7 @@ func (h *Handler) initializeSandboxDeployment(w http.ResponseWriter, r *http.Req // @Accept json // @Param body body api.SandboxDeploymentChangeInput true "Replacement deployment selection" // @Success 200 {object} store.RuntimeDeploymentView -// @Failure 400,401,409,500,503 {object} CoreErrorResponse +// @Failure 400,401,409,413,500,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/deployment [put] func (h *Handler) updateSandboxDeployment(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONBody(w, r) @@ -150,7 +150,7 @@ func (h *Handler) updateSandboxDeployment(w http.ResponseWriter, r *http.Request // @Accept json // @Param body body store.SandboxResetRequest true "Reset mode and current deployment generation" // @Success 200 {object} store.RuntimeDeploymentView -// @Failure 400,401,409,500,503 {object} CoreErrorResponse +// @Failure 400,401,409,413,500,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/deployment/reset [post] func (h *Handler) startSandboxReset(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONBodyLimit(w, r, 4096, "Reset request is too large.") diff --git a/services/agents-api/internal/api/sandbox_e2b_discovery.go b/services/agents-api/internal/api/sandbox_e2b_discovery.go index 577852b67..9d9716600 100644 --- a/services/agents-api/internal/api/sandbox_e2b_discovery.go +++ b/services/agents-api/internal/api/sandbox_e2b_discovery.go @@ -33,7 +33,7 @@ func WithSandboxE2BDiscovery(discover func(context.Context, SandboxE2BDiscoveryI // @Security DeploymentAdminAuth // @Param body body api.SandboxE2BDiscoveryInput true "Transient E2B connection" // @Success 200 {object} api.SandboxE2BDiscoveryResult -// @Failure 400,401,503 {object} CoreErrorResponse +// @Failure 400,401,413,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/e2b/templates [post] func (h *Handler) discoverSandboxE2BTemplates(w http.ResponseWriter, r *http.Request) { h.discoverSandboxE2B(w, r, "") @@ -48,7 +48,7 @@ func (h *Handler) discoverSandboxE2BTemplates(w http.ResponseWriter, r *http.Req // @Param template_id path string true "Template ID" // @Param body body api.SandboxE2BDiscoveryInput true "Transient E2B connection" // @Success 200 {object} api.SandboxE2BDiscoveryResult -// @Failure 400,401,503 {object} CoreErrorResponse +// @Failure 400,401,413,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/e2b/templates/{template_id}/builds [post] func (h *Handler) discoverSandboxE2BBuilds(w http.ResponseWriter, r *http.Request) { h.discoverSandboxE2B(w, r, chi.URLParam(r, "template_id")) diff --git a/services/agents-api/internal/api/sandbox_manager.go b/services/agents-api/internal/api/sandbox_manager.go index d88883ce7..51d9ffd4e 100644 --- a/services/agents-api/internal/api/sandbox_manager.go +++ b/services/agents-api/internal/api/sandbox_manager.go @@ -110,7 +110,7 @@ func (h *Handler) sandboxNodes(w http.ResponseWriter, r *http.Request) { // @Accept json // @Param body body store.RuntimeNodeUpdate true "Request" // @Success 200 {object} api.SandboxMutationResponse -// @Failure 400,401,404,409,500,503 {object} CoreErrorResponse +// @Failure 400,401,404,409,413,500,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/nodes/{node_id} [patch] func (h *Handler) updateSandboxNode(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONBody(w, r) @@ -174,7 +174,7 @@ func (h *Handler) sandboxAllocations(w http.ResponseWriter, r *http.Request) { // @Accept json // @Param body body api.SandboxEnrollmentTokenRequest true "Request" // @Success 201 {object} api.SandboxEnrollmentToken -// @Failure 400,401,404,409,500,503 {object} CoreErrorResponse +// @Failure 400,401,404,409,413,500,503 {object} CoreErrorResponse // @Router /core/v1/sandbox/enrollment-tokens [post] func (h *Handler) createSandboxEnrollment(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONBody(w, r) @@ -209,7 +209,7 @@ func (h *Handler) createSandboxEnrollment(w http.ResponseWriter, r *http.Request // @Accept json // @Param body body store.RuntimeNodeEnrollment true "Request" // @Success 201 {object} store.RuntimeNodeIdentity -// @Failure 400,401,404,409,500,503 {object} v1.ErrorResponse +// @Failure 400,401,404,409,413,500,503 {object} v1.ErrorResponse // @Router /api/v1/sandbox-node/enroll [post] func (h *Handler) enrollSandboxNode(w http.ResponseWriter, r *http.Request) { token, ok := sandboxBearer(r) diff --git a/services/agents-api/internal/api/session_deletion.go b/services/agents-api/internal/api/session_deletion.go index 48071f683..bef5d432d 100644 --- a/services/agents-api/internal/api/session_deletion.go +++ b/services/agents-api/internal/api/session_deletion.go @@ -18,7 +18,7 @@ import ( // @Param OpenAI-Beta header string true "agents=v1" // @Param session_id path string true "Session ID" // @Success 200 {object} v1.SessionDeleted -// @Failure 400,401,404,409,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,409,413,500,503 {object} v1.ErrorResponse // @Router /agents/sessions/{session_id} [delete] func (h *Handler) deleteSession(w http.ResponseWriter, r *http.Request) { body, ok := readJSONBody(w, r) diff --git a/services/agents-api/internal/api/session_metadata.go b/services/agents-api/internal/api/session_metadata.go index 718eaecd8..674afbed0 100644 --- a/services/agents-api/internal/api/session_metadata.go +++ b/services/agents-api/internal/api/session_metadata.go @@ -23,7 +23,7 @@ import ( // @Param session_id path string true "Session ID" // @Param body body v1.UpdateSessionRequest true "Session metadata" // @Success 200 {object} v1.Session -// @Failure 400,401,404,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /agents/sessions/{session_id} [post] func (h *Handler) updateSession(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONObject(w, r) diff --git a/services/agents-api/internal/api/skills.go b/services/agents-api/internal/api/skills.go index ae326fb1c..b37a6a977 100644 --- a/services/agents-api/internal/api/skills.go +++ b/services/agents-api/internal/api/skills.go @@ -57,6 +57,7 @@ func (h *Handler) skillsReady(w http.ResponseWriter) bool { // @Security BearerAuth // @Param skill_id path string true "Skill ID" // @Success 200 {object} v1.Skill +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id} [get] func (h *Handler) getSkill(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { @@ -79,6 +80,7 @@ func (h *Handler) getSkill(w http.ResponseWriter, r *http.Request) { // @Param skill_id path string true "Skill ID" // @Param body body v1.SkillUpdateRequest true "Default version" // @Success 200 {object} v1.Skill +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id} [post] func (h *Handler) updateSkill(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { @@ -108,6 +110,7 @@ func (h *Handler) updateSkill(w http.ResponseWriter, r *http.Request) { // @Security BearerAuth // @Param skill_id path string true "Skill ID" // @Success 200 {object} v1.SkillDeleted +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id} [delete] func (h *Handler) deleteSkill(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { @@ -128,6 +131,7 @@ func (h *Handler) deleteSkill(w http.ResponseWriter, r *http.Request) { // @Param skill_id path string true "Skill ID" // @Param version path string true "Concrete version number" // @Success 200 {object} v1.SkillVersion +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id}/versions/{version} [get] func (h *Handler) getSkillVersion(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { @@ -149,6 +153,7 @@ func (h *Handler) getSkillVersion(w http.ResponseWriter, r *http.Request) { // @Param skill_id path string true "Skill ID" // @Param version path string true "Concrete version number" // @Success 200 {object} v1.SkillVersionDeleted +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id}/versions/{version} [delete] func (h *Handler) deleteSkillVersion(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { diff --git a/services/agents-api/internal/api/skills_list.go b/services/agents-api/internal/api/skills_list.go index 85ba28d11..5e0975a01 100644 --- a/services/agents-api/internal/api/skills_list.go +++ b/services/agents-api/internal/api/skills_list.go @@ -16,6 +16,7 @@ import ( // @Param limit query integer false "Page size; 0 returns an empty page" default(20) minimum(0) maximum(100) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) // @Success 200 {object} v1.SkillList +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills [get] func (h *Handler) listSkills(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { @@ -51,6 +52,7 @@ func (h *Handler) listSkills(w http.ResponseWriter, r *http.Request) { // @Param limit query integer false "Page size; 0 returns an empty page" default(20) minimum(0) maximum(100) // @Param order query string false "Version order; omit for descending, explicit empty values are invalid" Enums(asc,desc) // @Success 200 {object} v1.SkillVersionList +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id}/versions [get] func (h *Handler) listSkillVersions(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { diff --git a/services/agents-api/internal/api/skills_transfer.go b/services/agents-api/internal/api/skills_transfer.go index 70b748897..0e41bc5bc 100644 --- a/services/agents-api/internal/api/skills_transfer.go +++ b/services/agents-api/internal/api/skills_transfer.go @@ -21,6 +21,7 @@ import ( // @Security BearerAuth // @Param files formData file true "Skill ZIP or directory files" // @Success 200 {object} v1.Skill +// @Failure 400,401,413,500,503 {object} v1.ErrorResponse // @Router /skills [post] func (h *Handler) createSkill(w http.ResponseWriter, r *http.Request) { h.uploadSkill(w, r, false) } @@ -33,6 +34,7 @@ func (h *Handler) createSkill(w http.ResponseWriter, r *http.Request) { h.upload // @Param files formData file true "Skill ZIP or directory files" // @Param default formData boolean false "Set as default" // @Success 200 {object} v1.SkillVersion +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id}/versions [post] func (h *Handler) createSkillVersion(w http.ResponseWriter, r *http.Request) { h.uploadSkill(w, r, true) @@ -85,6 +87,7 @@ func (h *Handler) uploadSkill(w http.ResponseWriter, r *http.Request, version bo // @Security BearerAuth // @Param skill_id path string true "Skill ID" // @Success 200 {file} binary +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id}/content [get] func (h *Handler) skillContent(w http.ResponseWriter, r *http.Request) { if !h.skillsReady(w) { @@ -113,6 +116,7 @@ func (h *Handler) skillContent(w http.ResponseWriter, r *http.Request) { // @Param skill_id path string true "Skill ID" // @Param version path string true "Concrete version number" // @Success 200 {file} binary +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /skills/{skill_id}/versions/{version}/content [get] func (h *Handler) skillVersionContent(w http.ResponseWriter, r *http.Request) { h.skillContent(w, r) diff --git a/services/agents-api/internal/api/turns.go b/services/agents-api/internal/api/turns.go index 4f51d676b..a0f2bdfa5 100644 --- a/services/agents-api/internal/api/turns.go +++ b/services/agents-api/internal/api/turns.go @@ -20,7 +20,7 @@ import ( // @Param session_id path string true "Session ID" // @Param turn_id path string true "Turn ID" // @Success 200 {object} v1.Turn -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/sessions/{session_id}/turns/{turn_id} [get] func (h *Handler) getTurn(w http.ResponseWriter, r *http.Request) { sessionID := chi.URLParam(r, "session_id") @@ -53,7 +53,7 @@ func (h *Handler) getTurn(w http.ResponseWriter, r *http.Request) { // @Param limit query int false "Page size" minimum(1) maximum(100) default(20) // @Param order query string false "Creation order; omit for descending, explicit empty values are invalid" Enums(asc,desc) default(desc) // @Success 200 {object} v1.TurnList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /agents/sessions/{session_id}/turns [get] func (h *Handler) listTurns(w http.ResponseWriter, r *http.Request) { options, ok := readPage(w, r) diff --git a/services/agents-api/internal/api/vaults.go b/services/agents-api/internal/api/vaults.go index 90b547435..7be8d2591 100644 --- a/services/agents-api/internal/api/vaults.go +++ b/services/agents-api/internal/api/vaults.go @@ -29,7 +29,7 @@ type VaultStore interface { // @Param OpenAI-Beta header string true "agents=v1" // @Param body body v1.CreateVaultRequest true "Vault name and metadata" // @Success 201 {object} v1.Vault -// @Failure 400,401,413,500 {object} v1.ErrorResponse +// @Failure 400,401,413,500,503 {object} v1.ErrorResponse // @Router /vaults [post] func (h *Handler) createVault(w http.ResponseWriter, r *http.Request) { raw, ok := readJSONObject(w, r) @@ -89,7 +89,7 @@ func (h *Handler) createVault(w http.ResponseWriter, r *http.Request) { // @Param OpenAI-Beta header string true "agents=v1" // @Param vault_id path string true "Vault ID" // @Success 200 {object} v1.Vault -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /vaults/{vault_id} [get] func (h *Handler) getVault(w http.ResponseWriter, r *http.Request) { id := chi.URLParam(r, "vault_id") diff --git a/services/agents-api/internal/api/vaults_delete.go b/services/agents-api/internal/api/vaults_delete.go index c67367713..ac84910f1 100644 --- a/services/agents-api/internal/api/vaults_delete.go +++ b/services/agents-api/internal/api/vaults_delete.go @@ -15,7 +15,7 @@ import ( // @Param OpenAI-Beta header string true "agents=v1" // @Param vault_id path string true "Vault ID" // @Success 200 {object} v1.VaultDeleted -// @Failure 400,401,404,413,500 {object} v1.ErrorResponse +// @Failure 400,401,404,413,500,503 {object} v1.ErrorResponse // @Router /vaults/{vault_id} [delete] func (h *Handler) deleteVault(w http.ResponseWriter, r *http.Request) { body, ok := readJSONBody(w, r) diff --git a/services/agents-api/internal/api/vaults_list.go b/services/agents-api/internal/api/vaults_list.go index 56c8ae6ad..496e39c4e 100644 --- a/services/agents-api/internal/api/vaults_list.go +++ b/services/agents-api/internal/api/vaults_list.go @@ -18,7 +18,7 @@ import ( // @Param status query string false "Scalar status filter" Enums(active,archived) // @Param status[] query []string false "Array status filter; combined with status as a union" collectionFormat(multi) Enums(active,archived) // @Success 200 {object} v1.VaultList -// @Failure 400,401,404,500 {object} v1.ErrorResponse +// @Failure 400,401,404,500,503 {object} v1.ErrorResponse // @Router /vaults [get] func (h *Handler) listVaults(w http.ResponseWriter, r *http.Request) { options, statuses, ok := readVaultPage(w, r)