open-managed-agents 0.1.0

package/dist/src/control-plane/openapi/document.js

@@ -0,0 +1,282 @@
+import { FILES_API_BETA, MANAGED_AGENTS_BETA, SKILLS_API_BETA, } from "../api-constants.js";
+import { EVENT_TYPES } from "../../types/events.js";
+const DOCUMENTED_EVENT_TYPES = EVENT_TYPES;
+const TAG_DESCRIPTIONS = {
+    Agents: "Versioned Managed Agents definitions.",
+    Environments: "Sandbox execution environment configuration.",
+    Files: "Workspace uploads, session outputs, and downloads.",
+    Skills: "Custom reusable skill bundles and immutable versions.",
+    "Secrets (OMA)": "OMA-specific write-only workspace secrets.",
+    Vaults: "Vault and MCP credential lifecycle.",
+    Sessions: "Managed Agent session lifecycle.",
+    "Session events": "User input, event history, and SSE streaming.",
+    "Models (OMA)": "OMA-specific provider/model readiness catalog.",
+    "Administration (OMA)": "OMA-specific local workspace and API-key administration.",
+    "Operations (OMA)": "OMA-specific health and metrics endpoints.",
+};
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const jsonContent = (schema, example) => ({
+    "application/json": { schema, ...(example === undefined ? {} : { example }) },
+});
+const jsonResponse = (description, schema, example) => ({
+    description,
+    content: jsonContent(schema, example),
+});
+const noContent = (description) => ({ description });
+const jsonBody = (schema, required = true, example) => ({
+    required,
+    content: jsonContent(schema, example),
+});
+const multipartBody = (properties, required) => ({
+    required: true,
+    content: {
+        "multipart/form-data": {
+            schema: { type: "object", properties, required, additionalProperties: false },
+        },
+    },
+});
+const pathParam = (name, description) => ({
+    name,
+    in: "path",
+    required: true,
+    ...(description === undefined ? {} : { description }),
+    schema: { type: "string", minLength: 1 },
+});
+const queryParam = (name, schema, description) => ({
+    name,
+    in: "query",
+    required: false,
+    ...(description === undefined ? {} : { description }),
+    schema,
+});
+const headerParam = (name, schema, required, description) => ({
+    name,
+    in: "header",
+    required,
+    ...(description === undefined ? {} : { description }),
+    schema,
+});
+const limit = queryParam("limit", { type: "integer", minimum: 1, maximum: 100 });
+const page = queryParam("page", { type: "string", minLength: 1 }, "Opaque cursor; return it unchanged.");
+const includeArchived = queryParam("include_archived", { type: "boolean", default: false });
+const idempotencyKey = headerParam("idempotency-key", { type: "string", minLength: 1, maxLength: 255 }, false, "Optional idempotency key for safely retrying this write.");
+const commonErrors = {
+    "400": jsonResponse("Invalid request", ref("Error")),
+    "401": jsonResponse("Authentication failed", ref("Error")),
+    "404": jsonResponse("Resource or route not found", ref("Error")),
+    "409": jsonResponse("Concurrent modification or idempotency conflict", ref("Error")),
+    "413": jsonResponse("Request too large", ref("Error")),
+    "429": jsonResponse("Workspace admission limit exceeded", ref("Error")),
+    "500": jsonResponse("Internal server error", ref("Error")),
+};
+function responses(status, schema, description = "Success") {
+    return {
+        [String(status)]: schema === undefined ? noContent(description) : jsonResponse(description, schema),
+        ...commonErrors,
+    };
+}
+function route(contract) {
+    const { success, ...rest } = contract;
+    return {
+        ...rest,
+        responses: success?.mediaType === undefined
+            ? responses(success?.status ?? 200, success?.schema, success?.description ?? "Success")
+            : {
+                [String(success.status ?? 200)]: {
+                    description: success.description ?? "Success",
+                    content: {
+                        [success.mediaType]: { schema: success.schema ?? { type: "string" } },
+                    },
+                },
+                ...commonErrors,
+            },
+    };
+}
+const agentId = pathParam("id", "Agent ID.");
+const vaultId = pathParam("vaultId", "Vault ID.");
+const credentialId = pathParam("credentialId", "Vault credential ID.");
+const sessionId = pathParam("sessionId", "Session ID.");
+export const OPENAPI_ROUTE_CONTRACTS = [
+    route({ method: "get", path: "/health", operationId: "getHealth", tag: "Operations (OMA)", summary: "Check appliance health", auth: "none", success: { schema: ref("Health") } }),
+    route({ method: "get", path: "/metrics", operationId: "getMetrics", tag: "Operations (OMA)", summary: "Read Prometheus metrics", description: "This route is registered only when metrics are enabled and the deployment exposure policy permits it. Otherwise it returns 404.", auth: "metrics", success: { schema: { type: "string" }, mediaType: "text/plain", description: "Prometheus exposition" } }),
+    route({ method: "post", path: "/v1/agents", operationId: "createAgent", tag: "Agents", summary: "Create an agent", auth: "workspace", beta: "managed", requestBody: jsonBody(ref("CreateAgentRequest"), true, { name: "Coding agent", model: "claude-sonnet-5" }), success: { schema: ref("Agent") } }),
+    route({ method: "get", path: "/v1/agents", operationId: "listAgents", tag: "Agents", summary: "List agents", auth: "workspace", beta: "managed", parameters: [limit, page, includeArchived], success: { schema: ref("ForwardAgentPage") } }),
+    route({ method: "get", path: "/v1/agents/{id}/versions", operationId: "listAgentVersions", tag: "Agents", summary: "List immutable agent versions", auth: "workspace", beta: "managed", parameters: [agentId, limit, page], success: { schema: ref("AgentVersionsPage") } }),
+    route({ method: "get", path: "/v1/agents/{id}", operationId: "getAgent", tag: "Agents", summary: "Retrieve an agent or historical version", auth: "workspace", beta: "managed", parameters: [agentId, queryParam("version", { type: "integer", minimum: 1 })], success: { schema: ref("Agent") } }),
+    route({ method: "post", path: "/v1/agents/{id}", operationId: "updateAgent", tag: "Agents", summary: "Create a new immutable agent version", auth: "workspace", beta: "managed", parameters: [agentId], requestBody: jsonBody(ref("UpdateAgentRequest")), success: { schema: ref("Agent") } }),
+    route({ method: "post", path: "/v1/agents/{id}/archive", operationId: "archiveAgent", tag: "Agents", summary: "Archive an agent", auth: "workspace", beta: "managed", parameters: [agentId], success: { schema: ref("Agent") } }),
+    route({ method: "post", path: "/v1/environments", operationId: "createEnvironment", tag: "Environments", summary: "Create an environment", auth: "workspace", beta: "managed", requestBody: jsonBody(ref("CreateEnvironmentRequest")), success: { schema: ref("Environment") } }),
+    route({ method: "get", path: "/v1/environments", operationId: "listEnvironments", tag: "Environments", summary: "List environments", auth: "workspace", beta: "managed", parameters: [limit, page, includeArchived], success: { schema: ref("ForwardEnvironmentPage") } }),
+    route({ method: "get", path: "/v1/environments/networking-presets", operationId: "listEnvironmentNetworkingPresets", tag: "Environments", summary: "List safe networking presets and deployment capability", auth: "workspace", beta: "managed", success: { schema: ref("EnvironmentNetworkingPresetCatalog") } }),
+    route({ method: "post", path: "/v1/environments/networking-presets/validate", operationId: "validateEnvironmentNetworkingHosts", tag: "Environments", summary: "Validate and normalize a custom hostname allowlist", auth: "workspace", beta: "managed", requestBody: jsonBody(ref("ValidateEnvironmentNetworkingHostsRequest")), success: { schema: ref("ValidateEnvironmentNetworkingHostsResponse") } }),
+    route({ method: "get", path: "/v1/environments/{id}", operationId: "getEnvironment", tag: "Environments", summary: "Retrieve an environment", auth: "workspace", beta: "managed", parameters: [pathParam("id", "Environment ID.")], success: { schema: ref("Environment") } }),
+    route({ method: "post", path: "/v1/environments/{id}/archive", operationId: "archiveEnvironment", tag: "Environments", summary: "Archive an environment", auth: "workspace", beta: "managed", parameters: [pathParam("id", "Environment ID.")], success: { schema: ref("Environment") } }),
+    route({ method: "delete", path: "/v1/environments/{id}", operationId: "deleteEnvironment", tag: "Environments", summary: "Delete an unreferenced environment", description: "OMA deliberately refuses deletion while any durable session references the environment.", auth: "workspace", beta: "managed", parameters: [pathParam("id", "Environment ID.")], success: { schema: ref("DeletedEnvironment") } }),
+    route({ method: "post", path: "/v1/files", operationId: "uploadFile", tag: "Files", summary: "Upload a file", auth: "workspace", beta: "files", requestBody: multipartBody({ file: { type: "string", format: "binary" } }, ["file"]), success: { schema: ref("File") } }),
+    route({ method: "get", path: "/v1/files", operationId: "listFiles", tag: "Files", summary: "List files", auth: "workspace", beta: "files", parameters: [limit, queryParam("after_id", { type: "string" }), queryParam("before_id", { type: "string" }), queryParam("scope_id", { type: "string" })], success: { schema: ref("FilePage") } }),
+    route({ method: "get", path: "/v1/files/{id}", operationId: "getFile", tag: "Files", summary: "Retrieve file metadata", auth: "workspace", beta: "files", parameters: [pathParam("id", "File ID.")], success: { schema: ref("File") } }),
+    route({ method: "get", path: "/v1/files/{id}/content", operationId: "downloadFile", tag: "Files", summary: "Download file content", auth: "workspace", beta: "files", parameters: [pathParam("id", "File ID.")], success: { schema: { type: "string", format: "binary" }, mediaType: "application/octet-stream", description: "Raw file bytes" } }),
+    route({ method: "delete", path: "/v1/files/{id}", operationId: "deleteFile", tag: "Files", summary: "Delete a file", auth: "workspace", beta: "files", parameters: [pathParam("id", "File ID.")], success: { schema: ref("DeletedFile") } }),
+    route({ method: "post", path: "/v1/skills", operationId: "createSkill", tag: "Skills", summary: "Create a custom skill", auth: "workspace", beta: "skills", requestBody: multipartBody({ display_title: { type: "string" }, "files[]": { type: "array", items: { type: "string", format: "binary" }, minItems: 1 } }, ["files[]"]), success: { schema: ref("Skill") } }),
+    route({ method: "get", path: "/v1/skills", operationId: "listSkills", tag: "Skills", summary: "List skills", auth: "workspace", beta: "skills", parameters: [limit, page], success: { schema: ref("SkillPage") } }),
+    route({ method: "get", path: "/v1/skills/{id}", operationId: "getSkill", tag: "Skills", summary: "Retrieve a skill", auth: "workspace", beta: "skills", parameters: [pathParam("id", "Skill ID.")], success: { schema: ref("Skill") } }),
+    route({ method: "delete", path: "/v1/skills/{id}", operationId: "deleteSkill", tag: "Skills", summary: "Delete a skill", auth: "workspace", beta: "skills", parameters: [pathParam("id", "Skill ID.")], success: { schema: ref("DeletedSkill") } }),
+    route({ method: "post", path: "/v1/skills/{id}/versions", operationId: "createSkillVersion", tag: "Skills", summary: "Create a skill version", auth: "workspace", beta: "skills", parameters: [pathParam("id", "Skill ID.")], requestBody: multipartBody({ "files[]": { type: "array", items: { type: "string", format: "binary" }, minItems: 1 } }, ["files[]"]), success: { schema: ref("SkillVersion") } }),
+    route({ method: "get", path: "/v1/skills/{id}/versions", operationId: "listSkillVersions", tag: "Skills", summary: "List skill versions", auth: "workspace", beta: "skills", parameters: [pathParam("id", "Skill ID."), limit, page], success: { schema: ref("SkillVersionPage") } }),
+    route({ method: "get", path: "/v1/skills/{id}/versions/{version}", operationId: "getSkillVersion", tag: "Skills", summary: "Retrieve a skill version", auth: "workspace", beta: "skills", parameters: [pathParam("id", "Skill ID."), pathParam("version", "Version or latest.")], success: { schema: ref("SkillVersion") } }),
+    route({ method: "delete", path: "/v1/skills/{id}/versions/{version}", operationId: "deleteSkillVersion", tag: "Skills", summary: "Delete a skill version", auth: "workspace", beta: "skills", parameters: [pathParam("id", "Skill ID."), pathParam("version", "Version or latest.")], success: { schema: ref("DeletedSkillVersion") } }),
+    route({ method: "post", path: "/v1/secrets", operationId: "upsertSecret", tag: "Secrets (OMA)", summary: "Create or replace a write-only secret", auth: "workspace", beta: "managed", requestBody: jsonBody(ref("CreateSecretRequest")), success: { status: 201, schema: ref("Secret") } }),
+    route({ method: "get", path: "/v1/secrets", operationId: "listSecrets", tag: "Secrets (OMA)", summary: "List secret metadata", auth: "workspace", beta: "managed", success: { schema: { type: "array", items: ref("Secret") } } }),
+    route({ method: "delete", path: "/v1/secrets/{name}", operationId: "deleteSecret", tag: "Secrets (OMA)", summary: "Delete a secret", auth: "workspace", beta: "managed", parameters: [pathParam("name", "Secret name.")], success: { status: 204, description: "Deleted" } }),
+    route({ method: "post", path: "/v1/vaults", operationId: "createVault", tag: "Vaults", summary: "Create a vault", auth: "workspace", beta: "managed", requestBody: jsonBody(ref("CreateVaultRequest")), success: { schema: ref("Vault") } }),
+    route({ method: "get", path: "/v1/vaults", operationId: "listVaults", tag: "Vaults", summary: "List vaults", auth: "workspace", beta: "managed", parameters: [limit, page, includeArchived], success: { schema: ref("ForwardVaultPage") } }),
+    route({ method: "get", path: "/v1/vaults/{vaultId}", operationId: "getVault", tag: "Vaults", summary: "Retrieve a vault", auth: "workspace", beta: "managed", parameters: [vaultId], success: { schema: ref("Vault") } }),
+    route({ method: "post", path: "/v1/vaults/{vaultId}/archive", operationId: "archiveVault", tag: "Vaults", summary: "Archive a vault", auth: "workspace", beta: "managed", parameters: [vaultId], success: { schema: ref("Vault") } }),
+    route({ method: "post", path: "/v1/vaults/{vaultId}", operationId: "updateVault", tag: "Vaults", summary: "Update a vault", auth: "workspace", beta: "managed", parameters: [vaultId], requestBody: jsonBody(ref("UpdateVaultRequest")), success: { schema: ref("Vault") } }),
+    route({ method: "delete", path: "/v1/vaults/{vaultId}", operationId: "deleteVault", tag: "Vaults", summary: "Delete a vault", auth: "workspace", beta: "managed", parameters: [vaultId], success: { schema: ref("DeletedVault") } }),
+    route({ method: "post", path: "/v1/vaults/{vaultId}/credentials", operationId: "createVaultCredential", tag: "Vaults", summary: "Create a vault credential", auth: "workspace", beta: "managed", parameters: [vaultId], requestBody: jsonBody(ref("CreateCredentialRequest")), success: { schema: ref("VaultCredential") } }),
+    route({ method: "get", path: "/v1/vaults/{vaultId}/credentials", operationId: "listVaultCredentials", tag: "Vaults", summary: "List vault credentials", auth: "workspace", beta: "managed", parameters: [vaultId, limit, page, includeArchived], success: { schema: ref("ForwardCredentialPage") } }),
+    route({ method: "post", path: "/v1/vaults/{vaultId}/credentials/{credentialId}/archive", operationId: "archiveVaultCredential", tag: "Vaults", summary: "Archive a vault credential", auth: "workspace", beta: "managed", parameters: [vaultId, credentialId], success: { schema: ref("VaultCredential") } }),
+    route({ method: "post", path: "/v1/vaults/{vaultId}/credentials/{credentialId}/mcp_oauth_validate", operationId: "validateVaultCredential", tag: "Vaults", summary: "Validate an MCP OAuth credential", auth: "workspace", beta: "managed", parameters: [vaultId, credentialId], success: { schema: { type: "object", additionalProperties: true } } }),
+    route({ method: "get", path: "/v1/vaults/{vaultId}/credentials/{credentialId}", operationId: "getVaultCredential", tag: "Vaults", summary: "Retrieve vault credential metadata", auth: "workspace", beta: "managed", parameters: [vaultId, credentialId], success: { schema: ref("VaultCredential") } }),
+    route({ method: "post", path: "/v1/vaults/{vaultId}/credentials/{credentialId}", operationId: "updateVaultCredential", tag: "Vaults", summary: "Update a vault credential", auth: "workspace", beta: "managed", parameters: [vaultId, credentialId], requestBody: jsonBody(ref("UpdateCredentialRequest")), success: { schema: ref("VaultCredential") } }),
+    route({ method: "delete", path: "/v1/vaults/{vaultId}/credentials/{credentialId}", operationId: "deleteVaultCredential", tag: "Vaults", summary: "Delete a vault credential", auth: "workspace", beta: "managed", parameters: [vaultId, credentialId], success: { status: 204, description: "Deleted" } }),
+    route({ method: "post", path: "/v1/sessions", operationId: "createSession", tag: "Sessions", summary: "Create a session", auth: "workspace", beta: "managed", parameters: [idempotencyKey], requestBody: jsonBody(ref("CreateSessionRequest")), success: { schema: ref("Session") } }),
+    route({ method: "get", path: "/v1/sessions", operationId: "listSessions", tag: "Sessions", summary: "List sessions with forward/backward cursors", auth: "workspace", beta: "managed", parameters: [limit, page, queryParam("order", { type: "string", enum: ["asc", "desc"], default: "desc" }), queryParam("agent_id", { type: "string" }), includeArchived], success: { schema: ref("SessionPage") } }),
+    route({ method: "get", path: "/v1/sessions/{id}", operationId: "getSession", tag: "Sessions", summary: "Retrieve a session", auth: "workspace", beta: "managed", parameters: [pathParam("id", "Session ID.")], success: { schema: ref("Session") } }),
+    route({ method: "post", path: "/v1/sessions/{id}/archive", operationId: "archiveSession", tag: "Sessions", summary: "Archive an idle session", auth: "workspace", beta: "managed", parameters: [pathParam("id", "Session ID.")], success: { schema: ref("Session") } }),
+    route({ method: "delete", path: "/v1/sessions/{id}", operationId: "deleteSession", tag: "Sessions", summary: "Delete an idle session", auth: "workspace", beta: "managed", parameters: [pathParam("id", "Session ID.")], success: { schema: ref("DeletedSession") } }),
+    route({ method: "post", path: "/v1/sessions/{sessionId}/events", operationId: "sendSessionEvents", tag: "Session events", summary: "Send user events to a session", auth: "workspace", beta: "managed", parameters: [sessionId, idempotencyKey], requestBody: jsonBody(ref("SendEventsRequest"), true, { events: [{ type: "user.message", content: [{ type: "text", text: "Hello" }] }] }), success: { schema: ref("EventPage") } }),
+    route({ method: "get", path: "/v1/sessions/{sessionId}/events", operationId: "listSessionEvents", tag: "Session events", summary: "List session events", auth: "workspace", beta: "managed", parameters: [sessionId, limit, page, queryParam("order", { type: "string", enum: ["asc", "desc"] }), queryParam("types[]", { type: "array", items: { type: "string", enum: DOCUMENTED_EVENT_TYPES } }, "Repeat to filter by an event type currently emitted by OMA.")], success: { schema: ref("EventPage") } }),
+    route({ method: "get", path: "/v1/sessions/{sessionId}/events/stream", operationId: "streamSessionEvents", tag: "Session events", summary: "Stream persisted session events over SSE", description: "OMA streams complete persisted events. Assistant text is emitted as a buffered `agent.message` after generation, not as token-preview deltas. The unsupported `event_deltas[]` query parameter is rejected with HTTP 400.", auth: "workspace", beta: "managed", parameters: [sessionId, headerParam("last-event-id", { type: "string" }, false, "Resume after this event ID.")], success: { schema: { type: "string", description: "SSE frames with id, event, and JSON data fields." }, mediaType: "text/event-stream", description: "SSE stream" } }),
+    route({ method: "get", path: "/v1/model-catalog", operationId: "listModelCatalog", tag: "Models (OMA)", summary: "List deployment-enabled model catalog entries", description: "OMA-specific discovery endpoint for provider/model readiness. It never returns base URLs, credential sources, header values, file paths, raw Pi config, or secrets.", auth: "workspace", beta: "managed", parameters: [queryParam("provider", { type: "string", minLength: 1 }, "Exact provider id."), queryParam("available", { type: "boolean", default: false }, "When true, include only models with configured local credentials."), limit, page], success: { schema: ref("ModelCatalogPage") } }),
+    route({ method: "post", path: "/admin/workspaces", operationId: "adminCreateWorkspace", tag: "Administration (OMA)", summary: "Create a workspace", auth: "admin", requestBody: jsonBody(ref("AdminCreateWorkspaceRequest")), success: { status: 201, schema: ref("AdminWorkspace") } }),
+    route({ method: "get", path: "/admin/workspaces", operationId: "adminListWorkspaces", tag: "Administration (OMA)", summary: "List workspaces", auth: "admin", success: { schema: { type: "array", items: ref("AdminWorkspace") } } }),
+    route({ method: "get", path: "/admin/workspaces/{id}", operationId: "adminGetWorkspace", tag: "Administration (OMA)", summary: "Retrieve a workspace", auth: "admin", parameters: [pathParam("id", "Workspace ID.")], success: { schema: ref("AdminWorkspace") } }),
+    route({ method: "post", path: "/admin/workspaces/{id}/keys", operationId: "adminMintWorkspaceKey", tag: "Administration (OMA)", summary: "Mint a workspace API key", auth: "admin", parameters: [pathParam("id", "Workspace ID.")], requestBody: jsonBody(ref("AdminMintKeyRequest"), false), success: { status: 201, schema: ref("AdminMintedKey") } }),
+    route({ method: "get", path: "/admin/workspaces/{id}/keys", operationId: "adminListWorkspaceKeys", tag: "Administration (OMA)", summary: "List workspace API key metadata", auth: "admin", parameters: [pathParam("id", "Workspace ID.")], success: { schema: { type: "array", items: ref("AdminKeyMetadata") } } }),
+    route({ method: "get", path: "/admin/workspaces/{id}/mcp-credentials", operationId: "adminListWorkspaceMcpCredentials", tag: "Administration (OMA)", summary: "List token-free MCP credential operational metadata", auth: "admin", parameters: [pathParam("id", "Workspace ID."), limit, page], success: { schema: ref("GenericForwardPage") } }),
+    route({ method: "delete", path: "/admin/keys/{sha256}", operationId: "adminRevokeWorkspaceKey", tag: "Administration (OMA)", summary: "Revoke a workspace API key", auth: "admin", parameters: [pathParam("sha256", "SHA-256 key fingerprint.")], success: { schema: ref("AdminKeyMetadata") } }),
+];
+const schemas = {
+    Error: { type: "object", required: ["type", "error", "request_id"], properties: { type: { const: "error" }, error: { type: "object", required: ["type", "message"], properties: { type: { type: "string" }, message: { type: "string" } }, additionalProperties: true }, request_id: { type: "string" } }, additionalProperties: false },
+    JsonObject: { type: "object", additionalProperties: true },
+    StringMap: { type: "object", additionalProperties: { type: "string" } },
+    NullableString: { type: ["string", "null"] },
+    ModelInput: { oneOf: [{ type: "string" }, { type: "object", required: ["id"], properties: { provider: { type: "string", minLength: 1 }, id: { type: "string", minLength: 1 }, speed: { type: "string", enum: ["standard", "fast"] } }, additionalProperties: false }] },
+    CreateAgentRequest: { type: "object", required: ["name", "model"], properties: { name: { type: "string", minLength: 1 }, model: ref("ModelInput"), system: ref("NullableString"), description: ref("NullableString"), tools: { type: "array", items: ref("JsonObject") }, skills: { type: "array", items: ref("JsonObject") }, mcp_servers: { type: "array", items: ref("JsonObject") }, metadata: ref("StringMap"), multiagent: { type: "null", description: "Full multi-agent runtime is not implemented. Omit this field or send null." } }, additionalProperties: false },
+    UpdateAgentRequest: { type: "object", required: ["version"], properties: { version: { type: "integer", minimum: 1 }, name: { type: "string", minLength: 1 }, model: ref("ModelInput"), system: ref("NullableString"), description: ref("NullableString"), tools: { type: ["array", "null"], items: ref("JsonObject") }, skills: { type: ["array", "null"], items: ref("JsonObject") }, mcp_servers: { type: ["array", "null"], items: ref("JsonObject") }, metadata: { type: "object", additionalProperties: { type: ["string", "null"] } }, multiagent: { type: "null", description: "Full multi-agent runtime is not implemented. Omit this field or send null." } }, additionalProperties: false },
+    Agent: { type: "object", required: ["id", "type", "name", "model", "version", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "agent" }, name: { type: "string" }, model: { type: "object", required: ["provider", "id", "speed"], properties: { provider: { type: "string" }, id: { type: "string" }, speed: { enum: ["standard", "fast"] } }, additionalProperties: false }, system: ref("NullableString"), description: ref("NullableString"), tools: { type: "array", items: ref("JsonObject") }, skills: { type: "array", items: ref("JsonObject") }, mcp_servers: { type: "array", items: ref("JsonObject") }, metadata: ref("StringMap"), multiagent: { type: ["object", "null"] }, version: { type: "integer", minimum: 1 }, created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } }, additionalProperties: false },
+    CreateEnvironmentRequest: { type: "object", required: ["name", "config"], properties: { name: { type: "string", minLength: 1 }, config: ref("JsonObject") }, additionalProperties: false },
+    Environment: { type: "object", required: ["id", "type", "name", "config", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "environment" }, name: { type: "string" }, config: ref("JsonObject"), created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } } },
+    DeletedEnvironment: { type: "object", required: ["type", "id"], properties: { type: { const: "environment_deleted" }, id: { type: "string" } }, additionalProperties: false },
+    EnvironmentNetworkingPresetCatalog: { type: "object", required: ["type", "deployment", "presets", "custom"], properties: { type: { const: "environment_networking_presets" }, deployment: { type: "object", required: ["provider", "egress_supported", "reason"], properties: { provider: { type: ["string", "null"] }, egress_supported: { type: "boolean" }, reason: { type: ["string", "null"] } }, additionalProperties: false }, presets: { type: "array", items: { type: "object", required: ["id", "version", "name", "description", "networking"], properties: { id: { type: "string" }, version: { type: "integer", minimum: 1 }, name: { type: "string" }, description: { type: "string" }, networking: { type: "object", required: ["type", "allowed_hosts"], properties: { type: { const: "limited" }, allowed_hosts: { type: "array", items: { type: "string" } } }, additionalProperties: false } }, additionalProperties: false } }, custom: { type: "object", required: ["https_only", "wildcard_matches_bare_domain"], properties: { https_only: { const: true }, wildcard_matches_bare_domain: { const: false } }, additionalProperties: false } }, additionalProperties: false },
+    ValidateEnvironmentNetworkingHostsRequest: { type: "object", required: ["allowed_hosts"], properties: { allowed_hosts: { type: "array", items: { type: "string" } } }, additionalProperties: false },
+    ValidateEnvironmentNetworkingHostsResponse: { type: "object", required: ["allowed_hosts"], properties: { allowed_hosts: { type: "array", items: { type: "string" } } }, additionalProperties: false },
+    File: { type: "object", required: ["id", "type", "filename", "mime_type", "size_bytes", "created_at", "downloadable", "scope"], properties: { id: { type: "string" }, type: { const: "file" }, filename: { type: "string" }, mime_type: { type: "string" }, size_bytes: { type: "integer", minimum: 0 }, downloadable: { type: "boolean" }, scope: { type: ["object", "null"] }, created_at: { type: "string", format: "date-time" } }, additionalProperties: false },
+    DeletedFile: { type: "object", required: ["id", "type"], properties: { id: { type: "string" }, type: { const: "file_deleted" } }, additionalProperties: false },
+    Skill: { type: "object", required: ["id", "type", "display_title", "source", "latest_version", "created_at", "updated_at"], properties: { id: { type: "string" }, type: { const: "skill" }, display_title: { type: "string" }, source: { const: "custom" }, latest_version: { type: ["string", "null"] }, created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" } }, additionalProperties: false },
+    SkillVersion: { type: "object", required: ["id", "type", "skill_id", "version", "name", "description", "directory", "created_at"], properties: { id: { type: "string" }, type: { const: "skill_version" }, skill_id: { type: "string" }, version: { type: "string" }, name: { type: "string" }, description: { type: "string" }, directory: { type: "string" }, created_at: { type: "string", format: "date-time" } }, additionalProperties: false },
+    DeletedSkill: { type: "object", required: ["id", "type"], properties: { id: { type: "string" }, type: { const: "skill_deleted" } }, additionalProperties: false },
+    DeletedSkillVersion: { type: "object", required: ["id", "type"], properties: { id: { type: "string" }, type: { const: "skill_version_deleted" } }, additionalProperties: false },
+    CreateSecretRequest: { type: "object", required: ["name", "value"], properties: { name: { type: "string", minLength: 1, maxLength: 256 }, value: { type: "string", minLength: 1, writeOnly: true } }, additionalProperties: false },
+    Secret: { type: "object", required: ["id", "type", "name", "created_at", "updated_at"], properties: { id: { type: "string" }, type: { const: "secret" }, name: { type: "string" }, created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" } }, additionalProperties: false },
+    CreateVaultRequest: { type: "object", required: ["display_name"], properties: { display_name: { type: "string", minLength: 1 }, metadata: ref("StringMap") }, additionalProperties: false },
+    UpdateVaultRequest: { type: "object", properties: { display_name: { type: "string", minLength: 1 }, metadata: ref("StringMap") }, additionalProperties: false },
+    Vault: { type: "object", required: ["id", "type", "display_name", "metadata", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "vault" }, display_name: { type: "string" }, metadata: ref("StringMap"), created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } } },
+    DeletedVault: { type: "object", required: ["id", "type"], properties: { id: { type: "string" }, type: { const: "vault_deleted" } } },
+    CreateCredentialRequest: { type: "object", required: ["auth"], properties: { display_name: ref("NullableString"), metadata: ref("StringMap"), auth: ref("JsonObject") }, additionalProperties: false },
+    UpdateCredentialRequest: { type: "object", properties: { display_name: ref("NullableString"), metadata: ref("StringMap"), auth: ref("JsonObject") }, additionalProperties: false },
+    VaultCredential: { type: "object", required: ["id", "type", "vault_id", "metadata", "auth", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "vault_credential" }, vault_id: { type: "string" }, display_name: ref("NullableString"), metadata: ref("StringMap"), auth: ref("JsonObject"), created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } }, additionalProperties: false },
+    CreateSessionRequest: { type: "object", required: ["agent", "environment_id"], properties: { agent: { oneOf: [{ type: "string" }, { type: "object", required: ["type", "id"], properties: { type: { const: "agent" }, id: { type: "string" }, version: { type: "integer", minimum: 1 } }, additionalProperties: false }] }, environment_id: { type: "string" }, vault_ids: { type: "array", items: { type: "string" } }, title: ref("NullableString"), metadata: ref("StringMap"), resources: { type: "array", items: ref("JsonObject") } }, additionalProperties: false },
+    Session: { type: "object", required: ["id", "type", "agent", "environment_id", "vault_ids", "status", "metadata", "created_at", "updated_at", "archived_at", "resources"], properties: { id: { type: "string" }, type: { const: "session" }, agent: { type: "object", required: ["type", "id", "version"], properties: { type: { const: "agent" }, id: { type: "string" }, version: { type: "integer" } } }, environment_id: { type: "string" }, vault_ids: { type: "array", items: { type: "string" } }, status: { enum: ["idle", "running", "rescheduling", "terminated"] }, title: ref("NullableString"), metadata: ref("StringMap"), created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" }, usage: { type: "null" }, resources: { type: "array", items: ref("JsonObject") } }, additionalProperties: false },
+    DeletedSession: { type: "object", required: ["id", "type"], properties: { id: { type: "string" }, type: { const: "session_deleted" } }, additionalProperties: false },
+    Event: { type: "object", required: ["id", "type", "processed_at"], properties: { id: { type: "string" }, type: { type: "string", enum: DOCUMENTED_EVENT_TYPES }, processed_at: { type: ["string", "null"], format: "date-time" } }, additionalProperties: true },
+    SendEventsRequest: { type: "object", required: ["events"], properties: { events: { type: "array", minItems: 1, maxItems: 200, items: { oneOf: [{ type: "object", required: ["type", "content"], properties: { type: { const: "user.message" }, content: { type: "array", items: ref("JsonObject") } }, additionalProperties: false }, { type: "object", required: ["type"], properties: { type: { const: "user.interrupt" } }, additionalProperties: false }, { type: "object", required: ["type", "custom_tool_use_id"], properties: { type: { const: "user.custom_tool_result" }, custom_tool_use_id: { type: "string" }, content: { type: "array", items: ref("JsonObject") }, is_error: { type: "boolean" } }, additionalProperties: false }, { type: "object", required: ["type", "tool_use_id", "result"], properties: { type: { const: "user.tool_confirmation" }, tool_use_id: { type: "string" }, result: { enum: ["allow", "deny"] }, deny_message: ref("NullableString") }, additionalProperties: false }] } } }, additionalProperties: false },
+    ModelCatalogEntry: { type: "object", required: ["type", "provider", "id", "name", "provider_name", "reasoning", "input", "context_window", "max_output_tokens", "credentials_configured", "default"], properties: { type: { const: "model" }, provider: { type: "string" }, id: { type: "string" }, name: { type: "string" }, provider_name: { type: "string" }, reasoning: { type: "boolean" }, input: { type: "array", items: { type: "string" } }, context_window: { type: "integer", minimum: 0 }, max_output_tokens: { type: "integer", minimum: 0 }, credentials_configured: { type: "boolean" }, default: { type: "boolean" } }, additionalProperties: false },
+    AdminCreateWorkspaceRequest: { type: "object", required: ["name"], properties: { name: { type: "string", minLength: 1 } }, additionalProperties: false },
+    AdminMintKeyRequest: { type: "object", properties: { label: { type: "string", minLength: 1, default: "default" } }, additionalProperties: false },
+    AdminWorkspace: { type: "object", required: ["id", "name", "created_at"], properties: { id: { type: "string" }, name: { type: "string" }, created_at: { type: "string", format: "date-time" } }, additionalProperties: false },
+    AdminMintedKey: { type: "object", required: ["workspace_id", "label", "key_sha256", "api_key"], properties: { workspace_id: { type: "string" }, label: { type: "string" }, key_sha256: { type: "string" }, api_key: { type: "string", writeOnly: true } }, additionalProperties: false },
+    AdminKeyMetadata: { type: "object", required: ["key_sha256", "workspace_id", "label", "created_at", "revoked_at"], properties: { key_sha256: { type: "string" }, workspace_id: { type: "string" }, label: { type: "string" }, created_at: { type: "string", format: "date-time" }, revoked_at: { type: ["string", "null"], format: "date-time" } }, additionalProperties: false },
+    Health: { type: "object", required: ["status", "version", "uptime_seconds", "checks"], properties: { status: { enum: ["ok", "degraded"] }, version: { type: "string" }, uptime_seconds: { type: "integer", minimum: 0 }, checks: { type: "object", required: ["storage", "runtime"], properties: { storage: ref("HealthCheck"), runtime: ref("HealthCheck") }, additionalProperties: false } }, additionalProperties: false },
+    HealthCheck: { type: "object", required: ["status"], properties: { status: { enum: ["ok", "failed"] }, detail: { type: "string" } }, additionalProperties: false },
+};
+for (const [name, item] of [
+    ["ForwardAgentPage", "Agent"],
+    ["AgentVersionsPage", "Agent"],
+    ["ForwardEnvironmentPage", "Environment"],
+    ["SkillPage", "Skill"],
+    ["SkillVersionPage", "SkillVersion"],
+    ["ForwardVaultPage", "Vault"],
+    ["ForwardCredentialPage", "VaultCredential"],
+]) {
+    const hasMore = name !== "AgentVersionsPage";
+    schemas[name] = {
+        type: "object",
+        required: ["data", "next_page", ...(hasMore ? ["has_more"] : [])],
+        properties: {
+            data: { type: "array", items: ref(item) },
+            next_page: { type: ["string", "null"] },
+            ...(hasMore ? { has_more: { type: "boolean" } } : {}),
+        },
+        additionalProperties: false,
+    };
+}
+schemas.FilePage = { type: "object", required: ["data", "has_more", "first_id", "last_id"], properties: { data: { type: "array", items: ref("File") }, has_more: { type: "boolean" }, first_id: { type: ["string", "null"] }, last_id: { type: ["string", "null"] } }, additionalProperties: false };
+schemas.SessionPage = { type: "object", required: ["data", "next_page", "prev_page"], properties: { data: { type: "array", items: ref("Session") }, next_page: { type: ["string", "null"] }, prev_page: { type: ["string", "null"] } }, additionalProperties: false };
+schemas.EventPage = { type: "object", required: ["data"], properties: { data: { type: "array", items: ref("Event") }, next_page: { type: ["string", "null"] } }, additionalProperties: false };
+schemas.GenericForwardPage = { type: "object", required: ["data", "has_more", "next_page"], properties: { data: { type: "array", items: ref("JsonObject") }, has_more: { type: "boolean" }, next_page: { type: ["string", "null"] } }, additionalProperties: false };
+schemas.ModelCatalogPage = { type: "object", required: ["data", "next_page"], properties: { data: { type: "array", items: ref("ModelCatalogEntry") }, next_page: { type: ["string", "null"] } }, additionalProperties: false };
+function betaParameter(kind) {
+    const feature = kind === "files" ? FILES_API_BETA : kind === "skills" ? SKILLS_API_BETA : MANAGED_AGENTS_BETA;
+    const alternative = kind === "managed" ? "" : ` The general ${MANAGED_AGENTS_BETA} beta is also accepted.`;
+    return headerParam("anthropic-beta", { type: "string", example: feature }, true, `Required beta feature header. Multiple features are comma-separated.${alternative}`);
+}
+export function createOpenApiDocument() {
+    const paths = {};
+    for (const contract of OPENAPI_ROUTE_CONTRACTS) {
+        const parameters = [
+            ...(contract.beta === undefined ? [] : [betaParameter(contract.beta)]),
+            ...(contract.parameters ?? []),
+        ];
+        const operation = {
+            operationId: contract.operationId,
+            tags: [contract.tag],
+            summary: contract.summary,
+            ...(contract.description === undefined ? {} : { description: contract.description }),
+            security: contract.auth === "none"
+                ? []
+                : contract.auth === "metrics"
+                    ? [{}, { MetricsBearer: [] }]
+                    : [{ [contract.auth === "workspace" ? "WorkspaceApiKey" : "AdminApiKey"]: [] }],
+            ...(parameters.length === 0 ? {} : { parameters }),
+            ...(contract.requestBody === undefined ? {} : { requestBody: contract.requestBody }),
+            responses: contract.responses,
+        };
+        (paths[contract.path] ??= {})[contract.method] = operation;
+    }
+    return {
+        openapi: "3.1.0",
+        info: {
+            title: "Open Managed Agents API",
+            version: "0.0.1-alpha",
+            description: "The currently shipped OMA API surface. Unsupported Claude Managed Agents operations are intentionally omitted.",
+        },
+        servers: [{ url: "/", description: "This OMA appliance" }],
+        tags: [...new Set(OPENAPI_ROUTE_CONTRACTS.map((contract) => contract.tag))]
+            .map((name) => ({ name, description: TAG_DESCRIPTIONS[name] })),
+        paths,
+        components: {
+            securitySchemes: {
+                WorkspaceApiKey: { type: "apiKey", in: "header", name: "x-api-key", description: "Workspace-scoped API key." },
+                AdminApiKey: { type: "apiKey", in: "header", name: "x-admin-key", description: "Local appliance administrator key. Keep it out of URLs, cookies, and persistent browser storage." },
+                MetricsBearer: { type: "http", scheme: "bearer", description: "Optional deployment-configured metrics bearer token." },
+            },
+            schemas,
+        },
+    };
+}
+export function openApiContractRouteKeys() {
+    return OPENAPI_ROUTE_CONTRACTS.map((contract) => `${contract.method.toUpperCase()} ${contract.path}`).sort();
+}

package/dist/src/control-plane/openapi/routes.js

@@ -0,0 +1,78 @@
+import { createReadStream, realpathSync, statSync } from "node:fs";
+import { extname, resolve, sep } from "node:path";
+import { Readable } from "node:stream";
+import { createOpenApiDocument } from "./document.js";
+export const OPENAPI_DOCUMENT_PATH = "/openapi.json";
+export const OPENAPI_DOCS_MOUNT = "/docs";
+const CONTENT_TYPES = new Map([
+    [".css", "text/css; charset=utf-8"],
+    [".html", "text/html; charset=utf-8"],
+    [".js", "text/javascript; charset=utf-8"],
+]);
+const DOCS_CSP = [
+    "default-src 'none'",
+    "script-src 'self'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "font-src 'self' data:",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+].join("; ");
+export function registerOpenApiRoutes(app, config) {
+    const realRoot = realpathSync(resolve(config.root));
+    const serialized = JSON.stringify(createOpenApiDocument(), null, 2) + "\n";
+    app.get(OPENAPI_DOCUMENT_PATH, (c) => {
+        setDocsHeaders(c);
+        c.header("content-type", "application/json; charset=utf-8");
+        return c.body(serialized);
+    });
+    app.get(OPENAPI_DOCS_MOUNT, (c) => c.redirect(`${OPENAPI_DOCS_MOUNT}/`, 301));
+    app.get(`${OPENAPI_DOCS_MOUNT}/*`, (c) => {
+        const raw = c.req.path.slice(OPENAPI_DOCS_MOUNT.length + 1);
+        const relative = raw === "" ? "index.html" : decodeOrNull(raw);
+        if (relative === null || relative.includes("\0"))
+            return notFound(c);
+        const candidate = resolve(realRoot, relative);
+        if (!contains(realRoot, candidate))
+            return notFound(c);
+        let file;
+        try {
+            file = realpathSync(candidate);
+        }
+        catch {
+            return notFound(c);
+        }
+        if (!contains(realRoot, file) || !statSync(file).isFile())
+            return notFound(c);
+        const contentType = CONTENT_TYPES.get(extname(file));
+        if (contentType === undefined)
+            return notFound(c);
+        setDocsHeaders(c);
+        c.header("content-type", contentType);
+        return c.body(Readable.toWeb(createReadStream(file)));
+    });
+}
+function contains(root, candidate) {
+    return candidate === root || candidate.startsWith(root + sep);
+}
+function decodeOrNull(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+function notFound(c) {
+    setDocsHeaders(c);
+    return c.text("Not found\n", 404);
+}
+function setDocsHeaders(c) {
+    c.header("cache-control", "no-store");
+    c.header("content-security-policy", DOCS_CSP);
+    c.header("referrer-policy", "no-referrer");
+    c.header("x-content-type-options", "nosniff");
+    c.header("x-frame-options", "DENY");
+}

package/dist/src/control-plane/request-idempotency.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { conflict, invalidRequest, toApiErrorBody } from "./errors.js";
+export const IDEMPOTENCY_RESPONSE_TTL_MS = 24 * 60 * 60 * 1000;
+export const IDEMPOTENCY_ABANDONED_IN_PROGRESS_MS = 5 * 60 * 1000;
+export const IDEMPOTENCY_RETRY_AFTER_SECONDS = 5;
+export const IDEMPOTENCY_HEARTBEAT_INTERVAL_MS = 60 * 1000;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+export function validateIdempotencyKey(value) {
+    if (value.length === 0) {
+        throw invalidRequest("`Idempotency-Key` must not be empty");
+    }
+    if (value.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+        throw invalidRequest(`\`Idempotency-Key\` must be at most ${MAX_IDEMPOTENCY_KEY_LENGTH} characters`);
+    }
+    if (!/^[\x21-\x7E]+$/.test(value)) {
+        throw invalidRequest("`Idempotency-Key` must contain only visible ASCII characters");
+    }
+    return value;
+}
+export function requestFingerprint(method, concretePath, rawBody) {
+    const hash = createHash("sha256");
+    hash.update(method);
+    hash.update("\n");
+    hash.update(concretePath);
+    hash.update("\n");
+    hash.update(rawBody);
+    return hash.digest("hex");
+}
+export function reserveWindow(now = new Date()) {
+    return {
+        now: now.toISOString(),
+        expiresAt: new Date(now.getTime() + IDEMPOTENCY_RESPONSE_TTL_MS).toISOString(),
+        abandonedBefore: new Date(now.getTime() - IDEMPOTENCY_ABANDONED_IN_PROGRESS_MS).toISOString(),
+    };
+}
+export function completionWindow(now = new Date()) {
+    return {
+        now: now.toISOString(),
+        expiresAt: new Date(now.getTime() + IDEMPOTENCY_RESPONSE_TTL_MS).toISOString(),
+    };
+}
+export async function withIdempotencyReservationHeartbeat(ledger, input, operation) {
+    if (!ledger || !input)
+        return operation;
+    const refresh = () => {
+        ledger.refreshIdempotencyReservation({
+            ...input,
+            ...completionWindow(),
+        });
+    };
+    refresh();
+    const timer = setInterval(refresh, IDEMPOTENCY_HEARTBEAT_INTERVAL_MS);
+    timer.unref?.();
+    try {
+        return await operation;
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+export function idempotencyCompletion(workspaceId, idempotency, response, resource) {
+    return {
+        ...idempotency,
+        workspaceId,
+        responseStatus: response.status,
+        responseBody: response.body,
+        ...completionWindow(),
+        ...(resource === undefined
+            ? {}
+            : { resourceType: resource.type, resourceId: resource.id }),
+    };
+}
+export function idempotencyConflictResponse(requestId) {
+    // This is client retry guidance in seconds. It is intentionally much shorter
+    // than the abandoned in-progress threshold used for crash recovery.
+    const error = conflict("A request with this `Idempotency-Key` is already in progress; retry later");
+    return {
+        status: error.status,
+        body: toApiErrorBody(error, requestId),
+        headers: { "retry-after": String(IDEMPOTENCY_RETRY_AFTER_SECONDS) },
+    };
+}
+export function idempotencyMismatchError() {
+    return invalidRequest("`Idempotency-Key` was already used for a different request");
+}