{ "openapi": "3.1.0", "jsonSchemaDialect": "http://json-schema.org/draft-07/schema#", "info": { "title": "DesireCore Agent Service — public HTTP subset", "version": "1.0.0", "description": "Selected externally callable endpoints for an administrator-provided standalone instance. This document is a subset of the service, and is not an application release declaration. Consult the linked guides for deployment, authorization and asynchronous results." }, "servers": [ { "url": "https://{instanceHost}", "description": "Replace with the HTTPS address supplied by the administrator. This is not the public documentation site.", "variables": { "instanceHost": { "default": "your-instance.example", "description": "Actual instance host, including a nonstandard port when required." } } } ], "tags": [ { "name": "Connection", "description": "Instance identity and authenticated connection checks." }, { "name": "Webhook", "description": "Administrator-configured external event triggers." }, { "name": "Read-only", "description": "Owner read-only metadata and user-owned receipts." }, { "name": "Conversations", "description": "HTTP submission and admission lookup; asynchronous messages use Socket.IO." }, { "name": "Webhook management", "description": "Owner configuration, selected Tool grants and dedicated secret rotation." } ], "paths": { "/api/client-handshake": { "get": { "operationId": "getAgentServiceClientHandshake", "tags": [ "Connection" ], "summary": "Verify an existing instance credential and identify the service", "description": "Does not issue credentials. A 200 response does not establish that every optional capability is configured. Extension headers only request metadata; they do not grant permissions.", "externalDocs": { "url": "https://docs.desirecore.com/api/connection-and-auth" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "x-desirecore-handshake-extensions", "in": "header", "required": false, "description": "Optional comma-separated extensions: product-identity, query-dispatch, deployment-capabilities. Unrecognized names are ignored.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authenticated service identity and capability metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientHandshake" }, "example": { "service": "desirecore-agent-service", "apiProtocolVersion": "1", "serverVersion": "10.0.180", "instanceId": "inst_0123456789abcdefghijklmnopqrstuv", "deploymentMode": "external", "clientCompatibility": { "minimumVersion": "0.0.0", "maximumVersion": null }, "capabilities": { "workflow": false, "mediaSignedUrl": true, "pdfRendering": false, "localPairing": true, "queryRequestIdEcho": true }, "authentication": { "kind": "instance-token", "scopes": [ "owner" ] }, "serverTime": "2026-10-14T08:00:00.000Z" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store, private" } }, "Vary": { "schema": { "type": "string" } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "500": { "description": "Service identity cannot be read or another server failure occurred; the response does not expose the data-directory path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameworkError" } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/webhook/{agent_id}": { "post": { "operationId": "triggerAgentWebhook", "tags": [ "Webhook" ], "summary": "Trigger an administrator-configured Agent event", "description": "The Agent and event must already be enabled and configured. Receives an event and starts background processing. A 200 acknowledgement contains no Run ID or final result. There is no public idempotency key; repeated requests may trigger repeated executions.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "WebhookSecret": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "The administrator-provided Agent ID, not its display name.", "schema": { "type": "string" } } ], "x-max-body-bytes": 1048576, "requestBody": { "required": true, "description": "The complete JSON body must be at most 1 MiB. Only event and payload are accepted at the top level.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" }, "example": { "event": "demo.ping", "payload": { "message": "Test event: please confirm receipt." } } } } }, "responses": { "200": { "description": "The event was accepted; background execution may subsequently fail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAccepted" }, "example": { "accepted": true, "agentId": "your-agent-id", "event": "demo.ping" } } } }, "400": { "description": "Request Schema, unknown event, or JSON parsing error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebhookInvalidBody" }, { "$ref": "#/components/schemas/WebhookUnknownEvent" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The configured dedicated Webhook secret was not supplied correctly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAuthenticationError" } } } }, "403": { "description": "The target Agent has no required external secret, or the browser Origin is not allowed.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebhookSecretRequired" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "404": { "description": "The Agent does not exist or its Webhook is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookNotFound" } } } }, "413": { "description": "The JSON request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameworkError" } } } }, "415": { "description": "The request Content-Type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameworkError" } } } }, "500": { "description": "The Agent configuration cannot be parsed or another server failure occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebhookConfigurationError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/agents": { "get": { "operationId": "listAgents", "tags": [ "Read-only" ], "summary": "List Agent summaries", "description": "Read-only instance-owner access. Returns summaries visible to the current trusted user.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs#list-agents" }, "security": [ { "InstanceToken": [] } ], "parameters": [], "responses": { "200": { "description": "Agent summary list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" }, "example": { "agents": [ { "id": "your-agent-id", "name": "Example Agent", "skillsCount": 0, "toolsCount": 0, "heartbeatEnabled": false, "hasGit": false, "isCoreAgent": false, "status": "idle" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "500": { "description": "An unexpected server failure occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperationsError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/runs": { "get": { "operationId": "listRuns", "tags": [ "Read-only" ], "summary": "List Run metadata", "description": "Owner access to instance-level Run metadata. Filters combine with AND before limit is applied. This endpoint has no offset or total field and does not promise per-user isolation.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs#list-runs" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 50 }, "description": "Single positive decimal safe integer. Repeated, empty, fractional and mixed values are rejected." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional exact filter; combined with the other supplied filters using AND." }, { "name": "delegated_by", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional exact filter; combined with the other supplied filters using AND." }, { "name": "parent_run_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional exact filter; combined with the other supplied filters using AND." } ], "responses": { "200": { "description": "Run metadata list; no total or offset wrapper.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunList" }, "example": { "runs": [ { "run_id": "00000000-0000-4000-8000-000000000001", "user_id": "example-owner", "agent_id": "your-agent-id", "started_at": "2026-10-14T01:00:00.000Z", "status": "idle" } ] } } } }, "400": { "description": "The limit query value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "500": { "description": "An unexpected server failure occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperationsError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/runs/{id}": { "get": { "operationId": "getRun", "tags": [ "Read-only" ], "summary": "Read Run metadata", "description": "Returns the RunMeta object directly. This owner endpoint reads instance-level metadata and does not promise per-user isolation.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs#get-run" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run ID." } ], "responses": { "200": { "description": "Run metadata without an enclosing run field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunMeta" }, "example": { "run_id": "00000000-0000-4000-8000-000000000001", "user_id": "example-owner", "agent_id": "your-agent-id", "started_at": "2026-10-14T01:00:00.000Z", "status": "idle" } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "404": { "description": "The Run was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "500": { "description": "An unexpected server failure occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperationsError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/runs/{id}/runtime-state": { "get": { "operationId": "getRunRuntimeState", "tags": [ "Read-only" ], "summary": "Read the current raw Run state", "description": "Preserves running, idle, completed and failed states. idle does not prove success of a particular submitted turn. A snapshot cannot replace authoritative checks performed by a mutating operation.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs#get-run-runtime-state" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Run ID." } ], "responses": { "200": { "description": "Raw Run identity and status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRuntimeState" }, "example": { "run_id": "00000000-0000-4000-8000-000000000001", "agent_id": "your-agent-id", "status": "idle" } } } }, "400": { "description": "The Run ID is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "404": { "description": "The Run runtime state is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "500": { "description": "An unexpected server failure occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperationsError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/runs/{id}/receipt": { "get": { "operationId": "listRunReceipts", "tags": [ "Read-only" ], "summary": "Read receipts belonging to the trusted user", "description": "The service checks trusted user ownership; a missing or foreign Run returns 404. Without offset and limit, returns all valid receipts in stored order. Supplying either parameter enables pagination from the newest receipts; effective limit is capped at 100 and offset at 10000.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs#list-run-receipts" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Run ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 20 }, "description": "Single positive safe integer. In paginated mode the effective value is capped at 100; omission defaults to 20 only when offset or limit enables pagination." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 }, "description": "Single non-negative safe integer; enables pagination and skips receipts backward from the newest. Effective value is capped at 10000." } ], "responses": { "200": { "description": "Run receipts; pagination fields appear when pagination is requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReceipts" }, "example": { "run_id": "00000000-0000-4000-8000-000000000001", "receipts": [ { "receipt_id": "example-receipt-id", "run_id": "00000000-0000-4000-8000-000000000001", "goal": "Reply to the test message", "input": "Please say hello.", "output": "Hello.", "tool_calls": [], "outcome": { "status": "success", "auto_completed": true }, "started_at": "2026-10-14T01:00:00.000Z", "completed_at": "2026-10-14T01:00:01.000Z" } ], "total": 1, "offset": 0, "limit": 20, "has_more": false, "skipped": 0 } } } }, "400": { "description": "The Run ID or pagination parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "401": { "description": "Authentication failed or no trusted user identity could be resolved.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperationsError" }, { "$ref": "#/components/schemas/InstanceAuthenticationError" } ] } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "404": { "description": "The Run is missing or belongs to another trusted user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "500": { "description": "An unexpected server failure occurred.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperationsError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/query/start": { "post": { "operationId": "startAgentQuery", "tags": [ "Conversations" ], "summary": "Submit a new query", "description": "Connect Socket.IO and subscribe to events first. Use its current socket.id as originSocketId; stable clientInstanceId belongs to Socket auth. HTTP 202 may precede durable commit and query:started.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs" }, "security": [ { "InstanceToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryStartRequest" }, "example": { "prompt": "Please reply with a short greeting.", "options": { "agentId": "your-agent-id", "conversationId": "integration-demo" }, "clientRequestId": "demo-start-1", "userMessageId": "demo-message-1", "originSocketId": "replace-with-current-socket-id" } } } }, "responses": { "202": { "description": "Transport/admission acknowledgement, not proof of durable commit, execution start or completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryAdmission" }, "example": { "ok": true, "clientRequestId": "demo-start-1" } } } }, "400": { "description": "Body validation, missing current origin socket, or query admission failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QueryAdmission" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "HTTP/socket principal mismatch, UI-context rejection, or an unapproved Origin.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QueryAdmission" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "409": { "description": "Conversation clear is in progress, or the request ID was reused with a different request digest. Follow retryable/busy/code rather than retrying all conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryAdmission" } } } }, "503": { "description": "The socket or handler is unavailable, request admission is still reserved/unknown, or the service is starting.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QueryAdmission" }, { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/query/follow-up": { "post": { "operationId": "followUpAgentQuery", "tags": [ "Conversations" ], "summary": "Submit a follow-up turn", "description": "Use the live sessionId from query:started and the current connected socket.id. Listen for query:followUpAccepted, query:message and the terminal event. Keep the same clientRequestId and frozen business body for eligible transport retries.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs" }, "security": [ { "InstanceToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryFollowUpRequest" }, "example": { "sessionId": "replace-with-query-started-session-id", "originSocketId": "replace-with-current-socket-id", "clientRequestId": "demo-follow-up-1", "message": { "id": "demo-message-2", "role": "user", "content": "Please continue briefly." } } } } }, "responses": { "202": { "description": "Transport/admission acknowledgement, not proof of durable commit, execution start or completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryAdmission" }, "example": { "ok": true, "sessionId": "replace-with-query-started-session-id", "clientRequestId": "demo-follow-up-1" } } } }, "400": { "description": "Body validation, missing current origin socket, or query admission failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QueryAdmission" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "HTTP/socket principal mismatch, UI-context rejection, or an unapproved Origin.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QueryAdmission" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "409": { "description": "Conversation clear is in progress, or the request ID was reused with a different request digest. Follow retryable/busy/code rather than retrying all conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryAdmission" } } } }, "503": { "description": "The socket or handler is unavailable, request admission is still reserved/unknown, or the service is starting.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QueryAdmission" }, { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/query/client-requests/lookup": { "post": { "operationId": "lookupQueryAdmissions", "tags": [ "Conversations" ], "summary": "Reconcile query admission by stable request IDs", "description": "Read-only admission lookup scoped to the trusted user and Agent. committed is a durable submission, not completion; reserved is an in-process reservation; absent is an observation and does not justify resending with a new ID; unknown requires reconciliation. Retention windows are returned by the service.", "externalDocs": { "url": "https://docs.desirecore.com/api/conversations-and-runs" }, "security": [ { "InstanceToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestLookupRequest" }, "example": { "agentId": "your-agent-id", "conversationId": "integration-demo", "requests": [ { "clientRequestId": "demo-start-1", "userMessageId": "demo-message-1" } ] } } } }, "responses": { "200": { "description": "Read-only admission and execution-witness observations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestLookupResponse" }, "example": { "protocolVersion": 1, "serverInstanceId": "example-process-generation", "observedAt": "2026-10-14T08:00:00.000Z", "autoReplayRetentionMs": 86400000, "tombstoneRetentionMs": 604800000, "results": [ { "clientRequestId": "demo-start-1", "status": "committed", "committedAt": "2026-10-14T07:59:59.000Z", "sessionId": "example-session-id", "committedServerInstance": "current", "executionWitness": "user-message" } ] } } } }, "400": { "description": "The lookup request does not match the Schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "A browser Origin is not allowed by this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginRejection" } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/agents/{id}/webhooks": { "get": { "operationId": "getAgentWebhookConfiguration", "tags": [ "Webhook management" ], "summary": "Read Webhook configuration and available Tools", "description": "Requires capabilities.webhookManagement === true from the authenticated handshake and the existing instance-owner credential. Lists event settings and Tool IDs the owner can select. Does not disclose the current secret value.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent ID from the instance, not its display name." } ], "responses": { "200": { "description": "Read Webhook configuration and available Tools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookManagement" }, "example": { "enabled": false, "hasSecret": false, "events": [], "availableTools": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store, private" } } } }, "400": { "description": "Invalid Agent/event ID, malformed management body, unavailable Tool ID, or no configured event/secret when enabling. Stable reason appears in error; no separate code field is required.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "An instance-owner management credential is required, or the Origin is not allowed. A trigger secret cannot manage this configuration.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "404": { "description": "The Agent or event was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "409": { "description": "Existing Webhook configuration is invalid; repair it before modifying events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "500": { "description": "The configuration could not be read or saved.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } }, "patch": { "operationId": "setAgentWebhookEnabled", "tags": [ "Webhook management" ], "summary": "Enable or pause existing Webhook events", "description": "Requires capabilities.webhookManagement === true from the authenticated handshake and the existing instance-owner credential. Enabling requires configured events and a dedicated secret. Pausing stops new trigger admission; it does not cancel work already accepted.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent ID from the instance, not its display name." } ], "responses": { "200": { "description": "Enable or pause existing Webhook events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnabledResponse" }, "example": { "success": true, "enabled": false } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store, private" } } } }, "400": { "description": "Invalid Agent/event ID, malformed management body, unavailable Tool ID, or no configured event/secret when enabling. Stable reason appears in error; no separate code field is required.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "An instance-owner management credential is required, or the Origin is not allowed. A trigger secret cannot manage this configuration.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "404": { "description": "The Agent or event was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "409": { "description": "Existing Webhook configuration is invalid; repair it before modifying events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "500": { "description": "The configuration could not be read or saved.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnabledRequest" }, "example": { "enabled": false } } } } } }, "/api/agents/{id}/webhooks/events/{event}": { "put": { "operationId": "upsertAgentWebhookEvent", "tags": [ "Webhook management" ], "summary": "Create or replace an event using selected available Tool IDs", "description": "Requires capabilities.webhookManagement === true from the authenticated handshake and the existing instance-owner credential. The service captures current Tool and file access limits. The caller cannot submit a permission snapshot. Saving enables Webhook and returns secret only when it was first generated; preserve it securely. An existing event is replaced.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent ID from the instance, not its display name." }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "not": { "enum": [ "constructor", "prototype", "__proto__" ] } }, "description": "Case-sensitive event name; reserved prototype names are rejected." } ], "responses": { "200": { "description": "Create or replace an event using selected available Tool IDs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventWritten" }, "example": { "success": true, "enabled": true, "event": "demo.ping", "secret": "example-secret-placeholder-do-not-use-12345" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store, private" } } } }, "400": { "description": "Invalid Agent/event ID, malformed management body, unavailable Tool ID, or no configured event/secret when enabling. Stable reason appears in error; no separate code field is required.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "An instance-owner management credential is required, or the Origin is not allowed. A trigger secret cannot manage this configuration.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "404": { "description": "The Agent or event was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "409": { "description": "Agent configuration changed while preparing the permission snapshot (webhook_configuration_changed), or existing configuration is malformed (webhook_configuration_invalid). Reload configuration and available tools, review permissions, then retry; repair malformed configuration first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "413": { "description": "The management body exceeds 128 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameworkError" } } } }, "415": { "description": "Use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameworkError" } } } }, "500": { "description": "The configuration could not be read or saved.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } }, "x-max-body-bytes": 131072, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventWrite" }, "example": { "promptTemplate": "Confirm receipt of {{message}} without using any tools.", "toolIds": [], "maxTurns": 5 } } } } }, "delete": { "operationId": "deleteAgentWebhookEvent", "tags": [ "Webhook management" ], "summary": "Delete one configured event", "description": "Requires capabilities.webhookManagement === true from the authenticated handshake and the existing instance-owner credential. Removes an existing event key, including historical keys outside the new-event naming rule. URL-encode the key. Removing the final event also disables Webhook. The response reports whether Webhook remains enabled.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent ID from the instance, not its display name." }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Existing event key, URL-encoded. Historical keys can be deleted even if they do not satisfy the new-event naming rule." } ], "responses": { "200": { "description": "Delete one configured event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnabledResponse" }, "example": { "success": true, "enabled": false } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store, private" } } } }, "400": { "description": "Invalid Agent/event ID, malformed management body, unavailable Tool ID, or no configured event/secret when enabling. Stable reason appears in error; no separate code field is required.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "An instance-owner management credential is required, or the Origin is not allowed. A trigger secret cannot manage this configuration.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "404": { "description": "The Agent or event was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "409": { "description": "Existing Webhook configuration is invalid; repair it before modifying events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "500": { "description": "The configuration could not be read or saved.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/agents/{id}/webhooks/secret/rotate": { "post": { "operationId": "rotateAgentWebhookSecret", "tags": [ "Webhook management" ], "summary": "Rotate the Agent dedicated Webhook secret", "description": "Requires capabilities.webhookManagement === true from the authenticated handshake and the existing instance-owner credential. Send no request body. The new secret applies to all events for this Agent. Save the returned value and update external senders; ordinary configuration reads cannot recover it.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent ID from the instance, not its display name." } ], "responses": { "200": { "description": "Rotate the Agent dedicated Webhook secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretRotation" }, "example": { "secret": "example-secret-placeholder-do-not-use-12345" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store, private" } } } }, "400": { "description": "Invalid Agent/event ID, malformed management body, unavailable Tool ID, or no configured event/secret when enabling. Stable reason appears in error; no separate code field is required.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "An instance-owner management credential is required, or the Origin is not allowed. A trigger secret cannot manage this configuration.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/OriginRejection" } ] } } } }, "404": { "description": "The Agent or event was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "409": { "description": "Existing Webhook configuration is invalid; repair it before modifying events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementError" } } } }, "500": { "description": "The configuration could not be read or saved.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ManagementError" }, { "$ref": "#/components/schemas/FrameworkError" } ] } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/api/agents/{agentId}/schedule-messages": { "get": { "operationId": "listAgentScheduleMessages", "tags": [ "Read-only" ], "summary": "Read visible persisted background messages", "description": "Returns only messages visible to the trusted user, filtering recipient and source ACL before pagination. Webhook delivery rows contain explicit SendUserMessage output, not every final model response or a per-request terminal result. Items are sorted newest first; limit defaults to 50 and is capped at 200.", "externalDocs": { "url": "https://docs.desirecore.com/api/agent-webhook" }, "security": [ { "InstanceToken": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 50 }, "description": "Positive safe integer; effective page size is capped at 200." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 } } ], "responses": { "200": { "description": "Visible background messages and effective pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleMessagePage" }, "example": { "items": [], "total": 0, "limit": 50, "offset": 0 } } } }, "400": { "description": "Pagination or source authorization failed; use the returned error message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "401": { "description": "The instance credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceAuthenticationError" } } } }, "403": { "description": "Pagination or source authorization failed; use the returned error message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "500": { "description": "Pagination or source authorization failed; use the returned error message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsError" } } } }, "503": { "description": "Startup is incomplete or instance authentication is not initialized.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceStarting" }, { "$ref": "#/components/schemas/InstanceTokenUninitialized" } ] } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present for service_not_ready; retry the read-only request after this many seconds." } } }, "default": { "description": "Other service or reverse-proxy failures. Preserve the HTTP status, Content-Type and response body; formats are not uniform.", "content": { "application/json": { "schema": {} }, "text/plain": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } } }, "components": { "securitySchemes": { "InstanceToken": { "type": "apiKey", "in": "header", "name": "X-Agent-Service-Token", "description": "Existing owner credential supplied by the instance administrator." }, "WebhookSecret": { "type": "http", "scheme": "bearer", "description": "Dedicated secret for the target Agent Webhook; not a provider API key or JWT." } }, "schemas": { "ClientHandshake": { "type": "object", "required": [ "service", "apiProtocolVersion", "serverVersion", "instanceId", "deploymentMode", "clientCompatibility", "capabilities", "authentication", "serverTime" ], "properties": { "service": { "type": "string", "const": "desirecore-agent-service", "description": "固定服务标记，用于拒绝非 DesireCore Agent Service 目标。" }, "apiProtocolVersion": { "type": "string", "const": "1", "description": "客户端握手和实例连接协议版本；不等同于应用版本。" }, "serverVersion": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "当前 Agent Service 随客户端发布的语义版本号。" }, "instanceId": { "type": "string", "pattern": "^inst_[A-Za-z0-9_-]{32}$", "description": "Agent Service 数据空间的稳定不透明身份。由服务端随机生成并持久化，不得由路径、用户、设备或 token 推导。" }, "deploymentMode": { "type": "string", "enum": [ "embedded", "owner", "external" ], "description": "Agent Service 运行形态：embedded=Electron 内嵌；owner=standalone owner 模式；external=standalone external 模式。" }, "clientCompatibility": { "type": "object", "required": [ "minimumVersion", "maximumVersion" ], "properties": { "minimumVersion": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "允许连接本服务的最低 DesireCore 客户端版本（含）。" }, "maximumVersion": { "type": [ "string", "null" ], "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "允许连接本服务的最高 DesireCore 客户端版本（含）；null 表示不设上限。" } }, "additionalProperties": false }, "capabilities": { "type": "object", "required": [ "workflow", "mediaSignedUrl" ], "properties": { "workflow": { "type": "boolean", "description": "当前部署是否具备可用且完整配置的 Workflow Service 能力。" }, "pdfRendering": { "type": "boolean", "description": "服务端宿主是否提供 HTML 转 PDF 引擎；缺席表示未知，不代表客户端具有打印传输。" }, "mediaSignedUrl": { "type": "boolean", "description": "当前实例是否可以签发供原生媒体标签使用的短期 HTTPS URL。" }, "queryRequestIdEcho": { "type": "boolean", "description": "服务端是否回显客户端 query 的 clientRequestId；缺席表示未知，客户端只能按实际事件观察，禁止按版本推断。" }, "webhookManagement": { "type": "boolean", "description": "是否支持所有者通过 Webhook 管理 API 配置事件、选择现有工具和轮换 secret；缺席或 false 表示该配置入口不可用。" }, "localPairing": { "type": "boolean" }, "localAttachSecret": { "type": "boolean" }, "objectStorageCapability": { "type": "boolean" }, "mailCapability": { "type": "boolean" } }, "additionalProperties": { "type": "boolean", "description": "未来新增的布尔能力位；旧客户端应忽略不认识的能力名。" } }, "authentication": { "type": "object", "required": [ "kind", "scopes" ], "properties": { "kind": { "type": "string", "enum": [ "embedded-capability", "instance-token" ], "description": "本次服务形态使用的客户端鉴权类型：embedded-capability 或 standalone instance-token。" }, "scopes": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "owner" ] }, "description": "认证凭据授予的实例作用域；第一版固定为 owner。" } }, "additionalProperties": false }, "serverTime": { "type": "string", "format": "date-time", "description": "服务端生成响应时的 ISO 8601 时间，用于诊断时钟偏差，不参与身份判断。" }, "product": { "type": "object", "required": [ "editionId", "appId", "productName", "buildKind", "appVersion" ], "properties": { "editionId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "maxLength": 128, "description": "服务所在应用的发行版 ID；同机接入发现据此标注候选实例属于哪个发行版。" }, "appId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "服务所在应用的 appId（macOS bundle id、Windows AUMID 前缀）。" }, "productName": { "type": "string", "minLength": 1, "maxLength": 128, "description": "服务所在应用的显示名。" }, "buildKind": { "type": "string", "enum": [ "dev", "prod" ], "description": "服务所在应用的构建形态：Electron 打包版为 prod，开发版为 dev；standalone 按运行环境判断。" }, "appVersion": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "服务所在应用的版本号，与 serverVersion 相同。" } }, "additionalProperties": false }, "capabilityDiagnostics": { "type": "object", "required": [ "pdfRendering" ], "properties": { "pdfRendering": { "type": [ "string", "null" ], "enum": [ "pdf_renderer_unavailable", null ] } }, "additionalProperties": false, "description": "仅协商 deployment-capabilities 时返回；原因是部署能力事实，不含配置、路径或凭据。" }, "queryDispatch": { "type": "object", "required": [ "serverInstanceId" ], "properties": { "serverInstanceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "当前服务进程启动代际，与 recovery.serverInstanceId 同源；重启即变化，不能当持久 instanceId 或认证凭证。" } }, "additionalProperties": false, "description": "仅协商 query-dispatch 扩展时返回；旧服务缺席本字段时不得伪造进程身份。" } }, "additionalProperties": false }, "WebhookRequest": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "事件标识，如 \"github.push\"" }, "payload": { "type": "object", "additionalProperties": {}, "description": "事件负载，prompt_template 中的 {{key}} 从此处提取" } }, "additionalProperties": false }, "WebhookAccepted": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "agentId": { "type": "string" }, "event": { "type": "string" } }, "required": [ "accepted", "agentId", "event" ], "additionalProperties": false }, "InstanceAuthenticationError": { "type": "object", "properties": { "error": { "type": "string", "const": "unauthorized" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, "OriginRejection": { "type": "object", "properties": { "error": { "type": "string", "const": "origin_not_allowed" }, "message": { "type": "string" } }, "required": [ "error" ], "additionalProperties": true }, "ServiceStarting": { "type": "object", "properties": { "status": { "type": "string", "const": "starting" }, "service": { "type": "string", "const": "agent-service" }, "code": { "type": "string", "const": "service_not_ready" } }, "required": [ "status", "service", "code" ], "additionalProperties": false }, "InstanceTokenUninitialized": { "type": "object", "properties": { "error": { "type": "string", "const": "instance_token_uninitialized" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, "WebhookAuthenticationError": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Invalid webhook secret", "Invalid embedded instance token" ] } }, "required": [ "error" ], "additionalProperties": false }, "WebhookSecretRequired": { "type": "object", "properties": { "error": { "type": "string", "const": "webhook_secret_required" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, "WebhookNotFound": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Agent not found", "Webhook not enabled for this agent" ] } }, "required": [ "error" ], "additionalProperties": false }, "WebhookInvalidBody": { "type": "object", "properties": { "error": { "type": "string", "const": "Invalid request body" }, "details": { "type": "array", "items": {} } }, "required": [ "error", "details" ], "additionalProperties": false }, "WebhookUnknownEvent": { "type": "object", "properties": { "error": { "type": "string", "pattern": "^Unknown event type: " } }, "required": [ "error" ], "additionalProperties": false }, "WebhookConfigurationError": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to parse agent.json" } }, "required": [ "error" ], "additionalProperties": false }, "FrameworkError": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "statusCode", "error", "message" ], "additionalProperties": true }, "AgentSummary": { "type": "object", "required": [ "id", "name", "skillsCount", "toolsCount", "heartbeatEnabled", "hasGit", "isCoreAgent" ], "properties": { "id": { "type": "string", "description": "智能体 ID（目录名）" }, "name": { "type": "string", "description": "智能体显示名称" }, "description": { "type": "string", "description": "智能体描述" }, "ui": { "type": "object", "description": "该智能体的界面呈现配置，仅作用于其会话，不改变平台设置", "properties": { "chat_bubble_mode": { "type": "string", "enum": [ "flat", "classic" ], "description": "消息样式：flat 为通栏，classic 为气泡；省略时跟随平台消息样式" } }, "additionalProperties": false }, "isCoreAgent": { "type": "boolean" }, "skillsCount": { "type": "number", "description": "技能数量", "minimum": 0 }, "toolsCount": { "type": "number", "description": "工具数量", "minimum": 0 }, "heartbeatEnabled": { "type": "boolean", "description": "心跳是否启用" }, "engine": { "type": "string", "description": "运行时引擎" }, "hasGit": { "type": "boolean", "description": "是否有 git 仓库" }, "hasRemote": { "type": "boolean" }, "status": { "type": "string", "description": "Agent 运行时状态（从 AgentRegistry 获取）", "enum": [ "online", "busy", "idle", "offline", "error", "recovery", "shutdown" ] }, "metadataError": { "type": "string", "enum": [ "missing", "unreadable", "invalid_json", "invalid_shape" ] }, "syncStatus": { "type": "string", "description": "Git 同步状态：synced（已同步）、ahead（本地有未推送提交）、behind（远程有更新）、conflict（存在冲突）、local_only（纯本地，无远程仓库）、uninitialized（未初始化 Git）", "enum": [ "synced", "ahead", "behind", "conflict", "local_only", "uninitialized" ] }, "avatar": { "type": "object", "description": "头像配置（来自 agent.json）", "properties": { "char": { "type": "string", "description": "显示字符" }, "color": { "type": "string", "description": "色系键名", "enum": [ "green", "blue", "purple", "orange", "red" ] }, "image": { "type": "object", "description": "图片头像配置（agent.json 原样透传）。**这里只说明配置存在，不代表文件可用**——判断能否渲染图片请看顶层 avatarImage", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "相对于 Agent 根目录的图片路径" } }, "additionalProperties": false }, "model": { "type": "object", "description": "沉浸式交互使用的 Agent 自定义 3D 模型配置", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "相对于 Agent 根目录的 GLB 文件路径" }, "body": { "type": "string", "description": "TalkingHead 模型体型提示", "enum": [ "F", "M" ] } }, "additionalProperties": false } }, "additionalProperties": false }, "avatarImage": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "string", "description": "缓存版本戳（`${size}-${mtimeMs}`），与该端点的 ETag 同源。值变化即表示图片已更换，客户端应丢弃旧缓存重新取图。不写进 agent.json：那会产生 git diff 噪声，且 Agent 直接覆盖图片文件时字段不会变，必然漂移。" }, "mimeType": { "type": "string", "description": "经 magic bytes 嗅探确认的真实 MIME 类型（不信任扩展名）", "enum": [ "image/png", "image/jpeg", "image/webp" ] } }, "additionalProperties": false }, "unread": { "type": "number", "description": "该 Agent 当前未读消息计数（手动多会话模式下为各话题未读之和，非手动模式为单会话计数）；无未读时不返回此字段" }, "pinned": { "type": "boolean", "description": "该 Agent 是否被用户置顶在侧栏最上方（来自用户级 preferences/agent-list.json）；未置顶时不返回此字段" }, "pinnedAt": { "type": "string", "description": "置顶时间 ISO 8601，多个置顶 Agent 之间的排序依据；未置顶时不返回此字段" }, "folded": { "type": "boolean", "description": "该 Agent 是否被收进侧栏的「折叠的聊天」分组（来自用户级 preferences/agent-list.json）；未折叠时不返回此字段" }, "groupOverride": { "type": "string", "enum": [ "general", "specialist" ], "description": "用户手动指定的侧栏分组，覆盖默认派生（默认派生 = 团队组长自动提升为通用，其余按 Agent 自身性质）；未手动指定时不返回此字段" }, "nestMembers": { "type": "boolean", "description": "该 Agent 作为团队组长时，其成员是否收纳到组长名下；用户级 preferences/agent-list.json 的显式选择优先，否则遵循团队 memberDisplay 默认值。未开启时不返回此字段" } }, "additionalProperties": false }, "RunMeta": { "type": "object", "required": [ "run_id", "user_id", "agent_id", "started_at", "status" ], "properties": { "run_id": { "type": "string", "description": "Run UUID，全局唯一标识符，用于查询和关联 Receipt" }, "user_id": { "type": "string", "description": "发起用户 ID" }, "agent_id": { "type": "string", "description": "Agent ID（对应 AgentFS 中的目录名）" }, "conversation_id": { "type": "string", "description": "对话 ID，用于关联同一对话的多次 Run（支持多轮对话场景）" }, "title": { "type": "string", "description": "会话标题（手动多会话模式下使用）：用户重命名后的自定义标题，或系统据首条消息生成的摘要标题" }, "title_source": { "type": "string", "enum": [ "custom", "auto" ], "description": "title 的来源：custom=用户手动重命名，auto=系统据首条用户消息自动生成（截断或 LLM 摘要）" }, "origin": { "type": "string", "enum": [ "user", "delegation" ], "description": "会话创建来源（手动多会话模式下使用）：user=用户手动新建，delegation=被其他 Agent 委派时自动新建" }, "background": { "type": "boolean" }, "inbound": { "type": "boolean", "description": "这一轮是不是「另一个 Agent 发来的消息」（SendMessage 来信）。**与 background 正交**：background 回答「该不该抢会话的前台控制槽」，本字段回答「这一轮在做什么」。来信已回归前台语义（与用户消息同路径），因此不再带 background；但「对方正在处理别人的来信」与「对方正在与用户对话」对**是否该打断**的判断截然不同，需要一个独立标记（见 agent/agent-activity.ts 的 kind 派生）。同 background，它描述的是**当前这一轮**，同一条 run 被复用时按当轮改写。" }, "started_at": { "type": "string", "description": "开始时间（ISO 8601 格式，如 2024-01-15T10:30:00Z）", "format": "date-time" }, "turn_started_at": { "type": "string", "description": "**当前这一轮**开始执行的时间（ISO 8601）。同一条 run 会跨轮复用，started_at 停在第一次创建的时刻——一条聊了三天的会话，它的 started_at 就是三天前，拿来算「已运行多久」会报出「已运行 3 天」这种荒谬值，并把忙碌载荷的等待/打断建议带偏。每次把 run 置为 running 的路径（创建、复用、activateRun、activateSessionMetaRun）都要刷新它。updatedAt 不能替代：它会被每次 appendMessage 推后，代表的是「最后一次活动」而非「本轮起点」。", "format": "date-time" }, "completed_at": { "type": "string", "description": "完成时间（ISO 8601 格式），仅 status 为 completed 或 failed 时有值", "format": "date-time" }, "status": { "type": "string", "description": "运行状态：running（执行中）、idle（空闲，等待下一轮对话）、completed（成功完成）、failed（执行失败，查看 failure_reason 字段了解原因）", "enum": [ "running", "idle", "completed", "failed" ] }, "failure_reason": { "type": "string", "description": "失败原因（仅 status=failed 时有值）：process_restart=进程重启时被回收的孤儿 run；timeout=执行超时被强制终结；stale=历史兼容值（旧版本曾把超过复用窗口的 idle run 错标为失败）；error=查询过程抛出错误", "enum": [ "process_restart", "timeout", "stale", "error" ] }, "interruption_reason": { "type": "string", "description": "最近一次未完成轮次的主动中止原因。Run 会回到 idle 以保留多轮会话复用能力，完整审计信息同时写入 Receipt", "enum": [ "user_abort", "agent_interrupt", "reset", "system_suspend", "process_shutdown", "process_restart", "orphan_reclaimed", "background_timeout" ] }, "interrupted_at": { "type": "string", "description": "最近一次主动中止发生时间（ISO 8601）。仅 interruption_reason 存在时有值", "format": "date-time" }, "pending_synthesis": { "type": "object", "required": [ "status", "interruption_reason", "created_at", "completed_tool_calls" ], "properties": { "status": { "type": "string", "const": "required", "description": "固定为 required：已完成工具事实存在，但最终业务解释尚未正常收口" }, "interruption_reason": { "type": "string", "enum": [ "user_abort", "agent_interrupt", "reset", "system_suspend", "process_shutdown", "process_restart", "orphan_reclaimed", "background_timeout" ] }, "created_at": { "type": "string", "format": "date-time", "description": "待综合状态创建时间（ISO 8601）" }, "completed_tool_calls": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "required": [ "invocation_id", "tool_name" ], "properties": { "invocation_id": { "type": "string", "maxLength": 256, "description": "已经成功完成的工具调用 ID，用于恢复时识别既成事实并避免重复执行" }, "tool_name": { "type": "string", "maxLength": 256, "description": "已经成功完成的模型可见工具名称，供审计和恢复提示使用" } }, "additionalProperties": false }, "description": "恢复时必须复用、不得仅为重取同一结果而再次执行的成功工具调用" } }, "additionalProperties": false, "description": "系统中断发生在工具成功之后、最终解释完成之前时持久化的恢复状态；正常综合成功后清除" }, "interrupted_turn_facts": { "type": "object", "required": [ "interruption_reason", "recorded_at", "deliveries" ], "properties": { "interruption_reason": { "type": "string", "description": "被记录轮次的中止原因（与 interruption_reason 字段同一枚举）。user_abort 时消费方可下「被用户停止」断言，其余原因只能弱化归因", "enum": [ "user_abort", "agent_interrupt", "reset", "system_suspend", "process_shutdown", "process_restart", "orphan_reclaimed", "background_timeout" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "deliveries": { "type": "array", "maxItems": 64, "items": { "type": "object", "required": [ "tool_name", "preview", "attachment_count", "delivery_status" ], "properties": { "tool_name": { "type": "string", "maxLength": 256, "description": "交付类工具的模型可见名称（builtin-tools/tool-effects 的 effect.class===\"delivery\" 派生名单成员，含历史 alias）" }, "preview": { "type": "string", "maxLength": 200, "description": "已投递内容的开头片段（取调用 input.message / input.content 的前 50 字符）。空串表示 input 缺失或非字符串（如 MailOperations 这类通用代理），消费方必须按「无法确认实际送达」的弱化措辞处理，不得下已送达断言" }, "attachment_count": { "type": "integer", "minimum": 0, "description": "调用 input.attachments 数组长度；0 表示无附件" }, "delivery_status": { "type": "string", "enum": [ "completed", "failed", "interrupted" ] } }, "additionalProperties": false }, "description": "被中断轮内交付类工具调用的终态清单（tool-effects 派生名单 + 已结算终态；同 toolCallId 去重；超上限时保留最近的条目）。空数组是权威事实「该轮没有任何交付」，消费方不得再退回尾窗启发式反推" } }, "additionalProperties": false }, "engine": { "type": "string", "description": "运行时引擎" }, "session_id": { "type": "string", "description": "关联的 Socket.IO session ID，用于实时通信和中断控制" }, "messageCount": { "type": "number", "description": "消息总数（由 SessionStore 维护）" }, "updatedAt": { "type": "string", "description": "最后更新时间（由 SessionStore 维护）" }, "cleared": { "type": "boolean", "description": "Tombstone 标记：用户清除对话后置为 true。会话列表和恢复逻辑会过滤掉此类 run，但 receipts/ 子目录保留，活动记录仍能读到该 run 的真实 token 消耗凭据（审计用）" }, "cleared_at": { "type": "string", "description": "Tombstone 写入时间（ISO 8601）。检查点清理按此时间计算 deletedRunRetentionMinutes；旧数据缺失时兼容 cleared=true", "format": "date-time" }, "archived_at": { "type": "string", "description": "会话归档时间（ISO 8601）。归档是独立于运行 status 的历史生命周期，归档 run 不再自动恢复，但消息和审计记录仍保留", "format": "date-time" }, "handoffFrom": { "type": "string", "description": "转交来源 Run ID（C-9.3）：本 run 承接自该 run 的会话转交（handoff）。回撤不跨转交边界，仅展示\"承接自 X\"链路" }, "handoffTo": { "type": "string", "description": "转交目标 Run ID（C-9.3）：本 run 已将会话转交给该 run。回撤不跨转交边界，仅展示\"已转交给 X\"链路" }, "team_id": { "type": "string", "description": "本 run 执行时所处的团队作用域。委派续跑（DelegateControl action=\"resume\"）必须按它重建执行环境——用调用方**当前**的 teamId 会让续跑落进另一个团队的 prompt 与共享工作目录，带着旧团队的历史在新环境里接力；缺省表示该 run 不属于任何团队。" }, "work_context_id": { "type": "string", "minLength": 1, "description": "本 Run 所属的稳定 Work Context ID。continue/resume 必须沿用，isolated/fork 必须记录新建结果；旧 Run 可缺省并由幂等 legacy backfill 建段。" }, "execution_attachment": { "type": "object", "required": [ "userId", "agentId", "runId" ], "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "agentId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "执行该 Run 的权威 Agent ID。" }, "runId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "承载本次执行的 DesireCore Run ID。" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的用户可见 Conversation ID；缺失表示该 Run 不属于对话时间线。" }, "workContextId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的稳定 Work Context ID，用于跨续跑保持同一工作语境。" }, "workflowRunId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的 Workflow Run ID；与 DesireCore Run ID 正交。" }, "cellId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的执行 Cell ID，表示服务实例所在的逻辑隔离单元。" }, "serviceInstanceId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的 Agent Service 实例 ID；出现时必须同时提供其所属 cellId。" }, "jobId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "attemptId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "capsuleId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" } }, "allOf": [ { "if": { "required": [ "serviceInstanceId" ] }, "then": { "required": [ "cellId" ] } }, { "if": { "required": [ "attemptId" ] }, "then": { "required": [ "jobId" ] } }, { "if": { "required": [ "capsuleId" ] }, "then": { "required": [ "jobId", "attemptId" ] } } ], "additionalProperties": false, "description": "本 Run 的权威执行归属；新 Run 由服务端构造，旧 Run 可缺失。其 user/agent/run/conversation/work-context 必须与外围 RunMeta 一致。" }, "work_context_selection": { "type": "object", "required": [ "context_mode", "origin" ], "properties": { "context_mode": { "type": "string", "enum": [ "continue", "isolated", "fork" ], "description": "必填且无默认值：continue=继续明确存在的同一任务上下文；isolated=不同新任务；fork=同一任务有意分叉。" }, "origin": { "type": "string", "enum": [ "delegate", "mention", "task", "workflow", "schedule", "webhook", "decision", "legacy" ] }, "work_context_id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "continue 必填：要继续的稳定 Work Context ID；禁止回退到目标 Agent 最近一次会话。" }, "source_work_context_id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "fork 必填：有意分叉的来源 Work Context ID。" }, "task_ref": { "type": "object", "required": [ "board_id", "task_id" ], "properties": { "board_id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1, "description": "TaskBoard 内稳定 Task ID。" }, "task_version": { "type": "integer", "minimum": 1, "description": "选择时观察到的 Task 版本快照；身份查重只使用 board_id + task_id。" } }, "additionalProperties": false }, "intent_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "context_reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "isolated/fork 必填：说明为何这是不同新任务或为何允许对同一 Task 有意分叉。" } }, "allOf": [ { "if": { "properties": { "context_mode": { "const": "continue" } }, "required": [ "context_mode" ] }, "then": { "required": [ "work_context_id" ], "not": { "anyOf": [ { "required": [ "source_work_context_id" ] }, { "required": [ "intent_id" ] } ] } } }, { "if": { "properties": { "context_mode": { "const": "isolated" } }, "required": [ "context_mode" ] }, "then": { "required": [ "context_reason" ], "anyOf": [ { "required": [ "task_ref" ] }, { "required": [ "intent_id" ] } ], "not": { "anyOf": [ { "required": [ "work_context_id" ] }, { "required": [ "source_work_context_id" ] } ] } } }, { "if": { "properties": { "context_mode": { "const": "fork" } }, "required": [ "context_mode" ] }, "then": { "required": [ "source_work_context_id", "task_ref", "context_reason" ], "not": { "anyOf": [ { "required": [ "work_context_id" ] }, { "required": [ "intent_id" ] } ] } } } ], "additionalProperties": false, "description": "启动此 Run 时调用方显式提交并经 preflight/commit 接受的 Work Context 选择快照。" }, "work_context_task_ref": { "type": "object", "required": [ "board_id", "task_id" ], "properties": { "board_id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1, "description": "TaskBoard 内稳定 Task ID。" }, "task_version": { "type": "integer", "minimum": 1, "description": "选择时观察到的 Task 版本快照；身份查重只使用 board_id + task_id。" } }, "additionalProperties": false }, "work_context_intent_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "work_context_origin": { "type": "string", "enum": [ "delegate", "mention", "task", "workflow", "schedule", "webhook", "decision", "legacy" ], "description": "此 Run 进入 Work Context 的权威入口快照。" }, "child_context": { "type": "object", "description": "原委派对子 Agent 上下文组装施加的**收紧**覆盖（Delegate 的 childContext 解析结果）。续跑必须按它重建，否则「只传 run_id 的裸续跑」会让原本被刻意收窄的上下文（memoryScope: none、关掉的能力、section 过滤）在续跑时全部放开——收紧只能保持或更严。形状与 ContextAssemblyOptions 的对应覆盖字段一致；缺省表示原委派未收紧。", "additionalProperties": true }, "child_tool_ceiling": { "type": "object", "description": "委派执行时的工具键与文件访问范围快照。tools 仅记录执行方当时的工具作为审计证据，不是父智能体的授权上限；持久 Agent 续跑使用执行方当前工具权限，并保留防递归限制。allowedReadDirs / allowedReadPaths / allowedWriteDirs 继续与调用方当前范围取交集；缺省的文件维度表示无限制。旧快照的工具键同样不再裁剪目标工具，形状错误仍拒绝恢复。", "additionalProperties": true }, "work_dir": { "type": "string", "description": "本 run 起跑时解析出的**基准**工作目录（团队共享目录 > 手动话题 Project > Agent/全局 effectiveCwd；不含运行时 worktree 绑定那层派生覆盖）。委派续跑据此确认「原来那次是在哪个目录里跑的」：承接来的历史里全是对旧目录中文件的读写，工作目录偏好在两次之间改过的话，续跑就会带着旧上下文在另一个项目里接力。⚠ 与 worktree_cwd 同一约定：**空字符串表示「起跑时确实没解析出工作目录」，字段缺席表示「该 run 创建于本字段引入之前」**——两者混为一谈的话，「当初没配、现在配了工作目录」会被闸门当成老数据跳过，而承接来的历史其实来自当时的进程默认目录。" }, "worktree_cwd": { "type": "string", "description": "本 run 起跑时实际附着的 Owner worktree 目录（`work_dir` 之上的派生覆盖）。与 work_dir 分开记：前者是用户偏好解析出的基准目录，这一条是运行时按 Owner 绑定的链接工作树。委派续跑两者都要一致——只比基准目录的话，源 run 当初挂在某个 worktree 上、而绑定后来被退出或改挂时闸门会放行，续跑于是回到主 checkout 或另一个工作树里接力。⚠ **空字符串表示「起跑时确实没有附着任何 worktree」，字段缺席表示「该 run 创建于本字段引入之前，无从得知」**——两者必须可区分：都写成缺席的话，「当初没挂、现在挂上了」这一格会被当成老数据跳过比较，而它恰恰是要拦的（历史来自主 checkout，续跑却跑进新工作树）。因此起跑路径**总是**写这个字段。" }, "resumedFrom": { "type": "string", "description": "同一执行连续性的来源 Run ID：由 DelegateControl(action=\"resume\") 或已接纳 Work Context continue 承接该 run。承接来的历史只作为运行时上下文喂给模型，**不落进本 run 的 messages.jsonl**，因此二次续跑必须沿这条链回溯收集，否则每续一次就丢掉更早那一段的历史与工具结果。与 handoffFrom 的区别：那是会话转交（用户换了对话对象），这是同一委派任务/Work Context 的接力。" }, "delegation": { "type": "object", "description": "委派溯源：仅由 Delegate 工具创建/复用的 run 有值，记录本 run 由哪个 Agent 的哪个父 run 委派产生。async 场景下父消息 metadata.delegate.children 在工具返回时为空，可通过此字段反查委派链（InspectRuns 工具 action=list 依赖它过滤子 run）", "required": [ "fromAgentId" ], "properties": { "fromAgentId": { "type": "string", "description": "发起委派的 Agent ID（delegation.fromAgentId，用户直接发起时为 owner）" }, "parentRunId": { "type": "string", "description": "委派方发起委派时所在的父 run ID。由父 sessionId 经 getRunIdBySession 反查；反查失败时缺省" }, "parentClientRequestId": { "type": "string", "minLength": 1, "description": "委派子 Run 创建时，由 ToolExecutor 从父 Agent **当前轮次**注入的可信 clientRequestId。它与可复用的 parentRunId 分开记录，用于证明子 Run 确实由父 Run 的这一轮产生；旧 Run 可缺省，但需要轮次级授权的新入口必须在缺失时失败关闭。" }, "mode": { "type": "string", "enum": [ "sync", "async", "via-messaging", "fan-out", "subtask" ], "description": "委派模式（handoff 不写 delegation，走 handoffFrom/handoffTo 链路；worker 无独立 run）。subtask=继承发起方会话上下文的子体，历史来源另记在 subtask_inherited_from。" } }, "additionalProperties": false }, "delivery_routing": { "type": "object", "required": [ "group", "audience" ], "properties": { "group": { "type": "string", "enum": [ "delegator-governed", "user-handoff", "run-inherited" ], "description": "委派交付路由分组：delegator-governed=先回委派方；user-handoff=目标会话直接服务用户；run-inherited=沿用目标 Run 已冻结受众。" }, "audience": { "oneOf": [ { "type": "object", "required": [ "type", "conversationId" ], "properties": { "type": { "type": "string", "const": "user", "description": "交付给当前用户可见会话。" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "用户接收交付的稳定会话 ID。" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "agentId" ], "properties": { "type": { "type": "string", "const": "delegator", "description": "交付给发起委派的主 Agent。" }, "agentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "委派方规范 Agent ID。" }, "parentRunId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "发起委派时的父 Run ID。" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "异步结果必须回到的父会话 ID。" }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "请求与最终交付的稳定关联 ID。" } }, "additionalProperties": false } ], "description": "准入时冻结的真实交付受众；只允许用户会话或委派方 Agent。" } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "group": { "const": "delegator-governed" } }, "required": [ "group" ] }, "then": { "properties": { "audience": { "type": "object", "required": [ "type", "agentId" ], "properties": { "type": { "type": "string", "const": "delegator", "description": "交付给发起委派的主 Agent。" }, "agentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "委派方规范 Agent ID。" }, "parentRunId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "发起委派时的父 Run ID。" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "异步结果必须回到的父会话 ID。" }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "请求与最终交付的稳定关联 ID。" } }, "additionalProperties": false } } } }, { "if": { "properties": { "group": { "const": "user-handoff" } }, "required": [ "group" ] }, "then": { "properties": { "audience": { "type": "object", "required": [ "type", "conversationId" ], "properties": { "type": { "type": "string", "const": "user", "description": "交付给当前用户可见会话。" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "用户接收交付的稳定会话 ID。" } }, "additionalProperties": false } } } } ], "description": "本 Run 在准入时冻结的交付路由分组与真实受众。委派/异步恢复/interject 不得根据当前激活会话重新推断；旧 Run 可缺省并按受控兼容规则只读派生。" }, "subtask_inherited_from": { "type": "object", "description": "本 run 作为 subtask 子体时，继承的那份对话历史的来源坐标。与 resumedFrom 是**两条不同的边**：resumedFrom 是「同一委派任务的接力」（承接子 run 自己的历史），本字段是「继承发起方会话的上下文」（历史来自另一条时间线）。混用会让委派续跑的链校验把 subtask 的来源当成祖先去比对归属五元组，而两者的归属口径本就不同。与 resumedFrom 同一约定：继承来的历史只作为运行时上下文喂给模型，**不落进本 run 的 messages.jsonl**，因此这是事后追溯「这条 run 看过谁的上下文」的唯一依据。", "properties": { "conversation_id": { "type": "string", "description": "历史来源会话 ID（发起方有话题时用这条；跨 run 归并后的规范视图）" }, "run_id": { "type": "string", "description": "历史来源 run ID（发起方本身是委派子 run、不属于任何会话时用这条）" } }, "additionalProperties": false } }, "additionalProperties": false }, "RunRuntimeState": { "type": "object", "required": [ "run_id", "agent_id", "status" ], "properties": { "run_id": { "type": "string", "description": "被查询的 Run ID；兼容普通 snake_case Run 与 checkpoint/rewind 产生的 camelCase fork Run" }, "agent_id": { "type": "string", "description": "该 Run 的权威 Agent 归属，用于审阅等破坏性操作在客户端预检时核对来源" }, "status": { "type": "string", "description": "Raw Run state. idle does not prove successful completion of a particular submitted turn.", "enum": [ "running", "idle", "completed", "failed" ] } }, "additionalProperties": false }, "RunReceipts": { "type": "object", "required": [ "run_id", "receipts" ], "properties": { "run_id": { "type": "string", "minLength": 1, "description": "当前可信用户有权读取的 Run ID。" }, "receipts": { "type": "array", "items": { "type": "object", "required": [ "run_id", "goal", "input", "output", "tool_calls", "outcome", "started_at", "completed_at" ], "properties": { "receipt_id": { "type": "string", "minLength": 1 }, "run_id": { "type": "string", "description": "关联的 Run ID" }, "execution_attachment": { "type": "object", "required": [ "userId", "agentId", "runId" ], "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "agentId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "执行该 Run 的权威 Agent ID。" }, "runId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "承载本次执行的 DesireCore Run ID。" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的用户可见 Conversation ID；缺失表示该 Run 不属于对话时间线。" }, "workContextId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的稳定 Work Context ID，用于跨续跑保持同一工作语境。" }, "workflowRunId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的 Workflow Run ID；与 DesireCore Run ID 正交。" }, "cellId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的执行 Cell ID，表示服务实例所在的逻辑隔离单元。" }, "serviceInstanceId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$", "description": "可选的 Agent Service 实例 ID；出现时必须同时提供其所属 cellId。" }, "jobId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "attemptId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" }, "capsuleId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^\\S+$" } }, "allOf": [ { "if": { "required": [ "serviceInstanceId" ] }, "then": { "required": [ "cellId" ] } }, { "if": { "required": [ "attemptId" ] }, "then": { "required": [ "jobId" ] } }, { "if": { "required": [ "capsuleId" ] }, "then": { "required": [ "jobId", "attemptId" ] } } ], "additionalProperties": false, "description": "生成本回执的完整 ID-only 执行归属；旧回执可缺失。" }, "goal": { "type": "string", "description": "执行目标（从用户输入中提取的任务描述）" }, "input": { "type": "string", "description": "用户原始输入（完整的用户消息）" }, "output": { "type": "string", "description": "最终输出文本（Agent 的完整响应）" }, "tool_calls": { "type": "array", "description": "工具调用列表（按执行顺序排列）", "items": { "type": "object", "required": [ "name" ], "properties": { "invocation_id": { "type": "string", "maxLength": 256, "description": "工具调用的全局唯一标识；用于在同名、重复或并行调用中准确关联开始与结束记录" }, "name": { "type": "string", "description": "工具名称（如 read_file、execute_command）" }, "input": { "description": "工具输入审计摘要；新记录仅保存 param_keys，不保存参数值或凭据，旧回执可保留原结构" }, "output_summary": { "type": "string", "description": "工具输出摘要（用于快速了解工具执行结果，非完整输出）" }, "duration_ms": { "type": "number", "description": "执行耗时（毫秒），用于性能分析", "minimum": 0 }, "started_at": { "type": "string", "description": "该工具调用开始时间（ISO 8601）", "format": "date-time" }, "completed_at": { "type": "string", "description": "该工具调用结束时间（ISO 8601）", "format": "date-time" }, "status": { "type": "string", "description": "工具调用执行结果：success（成功）、error（执行出错）", "enum": [ "success", "error" ] } }, "additionalProperties": false } }, "evidence": { "type": "string", "description": "决策依据（来自 thinking 或 reasoning 过程，解释 Agent 为何做出某些决策）" }, "outcome": { "type": "object", "required": [ "status", "auto_completed" ], "properties": { "status": { "type": "string", "description": "结果状态：success（成功完成）、partial（部分完成）、failed（执行失败）", "enum": [ "success", "partial", "failed" ] }, "auto_completed": { "type": "boolean", "description": "是否无人工干预完成（true 表示完全自动执行，false 表示需要用户确认或修正）" }, "user_edit_count": { "type": "number", "minimum": 0 }, "partial_result_available": { "type": "boolean", "description": "partial 回执是否包含可直接展示的已完成阶段结果，而不是空占位" }, "pending_synthesis": { "type": "boolean", "description": "是否仍需基于已完成工具事实生成最终业务解释；恢复时不得因此重复执行成功工具" } }, "additionalProperties": false }, "started_at": { "type": "string", "description": "开始时间（ISO 8601 格式）", "format": "date-time" }, "completed_at": { "type": "string", "description": "完成时间（ISO 8601 格式）", "format": "date-time" }, "duration_ms": { "type": "number", "description": "总耗时（毫秒），从开始到完成的完整时间", "minimum": 0 }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number", "description": "本次查询的非缓存输入 token 数（不含 cache_read / cache_write；per-query delta，不累计）", "minimum": 0 }, "output_tokens": { "type": "number", "description": "本次查询的输出 token 数（per-query delta，不累计）", "minimum": 0 }, "cost_usd": { "type": "number", "description": "本次查询的成本（美元，已包含缓存费用；per-query delta，不累计）", "minimum": 0 }, "provider": { "type": "string", "description": "使用的提供商标识（如 openai、anthropic）" }, "model": { "type": "string", "description": "使用的模型 ID（如 gpt-5-mini、claude-sonnet-4）" }, "cache_read_tokens": { "type": "number", "description": "本次查询从 prompt 缓存读取的 token 数（per-query delta，不累计）", "minimum": 0 }, "cache_write_tokens": { "type": "number", "description": "本次查询写入 prompt 缓存的 token 数（per-query delta，不累计）", "minimum": 0 } }, "additionalProperties": false }, "route_decision": { "type": "object", "additionalProperties": true }, "interruption_reason": { "type": "string", "description": "本条 partial 回执对应的主动中止原因。旧回执无此字段，保持向后兼容", "enum": [ "user_abort", "agent_interrupt", "reset", "system_suspend", "process_shutdown", "process_restart", "orphan_reclaimed", "background_timeout" ] } }, "additionalProperties": false }, "description": "该 Run 的结构化回执，按写入顺序。" }, "total": { "type": "integer", "minimum": 0, "description": "分页读取时该 Run 的有效 Receipt 总数。" }, "offset": { "type": "integer", "minimum": 0, "description": "从最新 Receipt 向前跳过的数量。" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "本页最多返回的 Receipt 数。" }, "has_more": { "type": "boolean", "description": "是否仍有更早的 Receipt 可按需加载。" }, "skipped": { "type": "integer", "minimum": 0, "description": "流式读取中跳过的损坏或超大行数。" } }, "additionalProperties": false, "description": "单个用户可见 Run 的 Receipt 响应。" }, "AgentList": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } } }, "additionalProperties": false }, "RunList": { "type": "object", "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunMeta" } } }, "additionalProperties": false }, "OperationsError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } }, "additionalProperties": false }, "QueryStartRequest": { "type": "object", "anyOf": [ { "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1 } } }, { "required": [ "mediaRefs" ], "properties": { "mediaRefs": { "type": "array", "minItems": 1 } } } ], "properties": { "prompt": { "type": "string", "description": "当前用户提交的提示词。" }, "options": { "type": "object", "properties": { "routingMode": { "type": "string", "enum": [ "smart", "fixed" ], "description": "模型路由模式。" }, "cwd": { "type": "string", "description": "当前轮授权工作目录。" }, "systemPrompt": { "type": "string", "description": "调用方附加的系统提示词。" }, "allowedTools": { "type": "array", "items": { "type": "string" }, "description": "允许的工具 ID。" }, "disallowedTools": { "type": "array", "items": { "type": "string" }, "description": "禁止的工具 ID。" }, "maxTurns": { "type": "number", "description": "最大 Agent 回合数。" }, "model": { "type": "string", "description": "模型名称。" }, "engine": { "const": "desirecore-engine", "description": "运行时引擎。" }, "provider": { "type": "string", "description": "Provider 协议族。" }, "providerId": { "type": "string", "description": "Provider 唯一 ID。" }, "apiKey": { "type": "string", "deprecated": true, "description": "Compatibility-only provider credential override. Configure provider credentials on the instance; this field does not authenticate the HTTP request." }, "reasoning": { "type": "string", "description": "本轮 reasoning 模式。" }, "reasoningDefault": { "type": "string" }, "suppressThinking": { "type": "boolean", "description": "仅隐藏公开思考展示，不改变模型思考强度或服务端私有协议回放。" }, "immersiveVoice": { "type": "object", "additionalProperties": false, "required": [ "modelSource", "reasoning" ], "properties": { "modelSource": { "type": "string", "enum": [ "conversation", "fast", "specified" ], "description": "当前对话、低延迟默认映射或人类指定的精确模型；低延迟不代表低费用。" }, "providerId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "specified 时使用的本地 Provider 接入面 ID。" }, "modelName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "specified 时使用的精确模型 ID。" }, "reasoning": { "type": "string", "enum": [ "follow", "low-latency", "auto", "off", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "follow 沿用对话；low-latency 只选择模型显式支持的最低档位；其他值为独立思考强度，不受显示思考开关影响。" } } }, "voiceSelectionRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "agentId": { "type": "string", "description": "当前 Agent ID。" }, "conversationHistory": { "type": "array", "items": { "$ref": "#/components/schemas/QueryStartRequest/definitions/conversationMessage" }, "description": "多轮连续性使用的结构化历史。" }, "conversationId": { "type": "string", "description": "对话稳定 ID。" }, "resumeFromDisk": { "type": "boolean", "description": "是否优先从磁盘恢复权威结构化历史。" }, "preferredRunId": { "type": "string", "description": "用户显式选择的恢复分支 run ID。" }, "excludeMessageIds": { "type": "array", "items": { "type": "string" }, "description": "恢复时剔除的本轮重发消息 ID。" }, "channel": { "type": "string", "description": "消息来源渠道。" }, "skillIds": { "type": "array", "items": { "type": "string" }, "description": "本轮显式选择的 Skill ID。" }, "skillArgs": { "type": "array", "items": { "type": "string" }, "description": "本轮 Skill 命令参数。" }, "fileReferences": { "type": "array", "items": { "type": "string" }, "description": "用户引用的文件路径。" }, "activeDocPath": { "type": "string", "description": "本次请求的可选文件参考路径。自动采集仅来自本窗口、属于当前会话的可见文档；显式传入或重试沿用已冻结的引用，不按当下界面重选。读取仍须授权，引用本身不表示编辑或附件交付请求。" }, "file": { "type": "object", "required": [ "name", "size", "type" ], "properties": { "name": { "type": "string", "description": "附件名称。" }, "size": { "type": "string", "description": "附件展示大小。" }, "type": { "type": "string", "description": "附件类型。" } }, "additionalProperties": false }, "teamId": { "type": "string", "description": "当前团队 ID。" } }, "additionalProperties": false }, "agentReferences": { "type": "array", "items": { "type": "object", "required": [ "occurrence_id", "target", "range" ], "properties": { "occurrence_id": { "type": "string", "minLength": 8, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "description": "客户端生成、在一次来源 revision 内稳定的 occurrence ID；同一 Agent 可出现多次。" }, "target": { "type": "object", "required": [ "agent_id", "display_name_snapshot" ], "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "description": "目标 Agent 的稳定语义 ID；仅允许 ASCII 字母、数字、下划线和连字符。" }, "display_name_snapshot": { "type": "string", "minLength": 1, "description": "服务端按 agent_id 从可信 Agent Registry 重建的显示快照；客户端同名字段只用于提交时 range 校验，不参与身份或 system prompt。" } }, "additionalProperties": false, "description": "稳定 Agent 引用；是否执行由来源契约决定，显示名不能单独触发投递。" }, "range": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "integer", "minimum": 0, "description": "正文 UTF-16 code unit 的起始偏移，包含。" }, "end": { "type": "integer", "minimum": 1, "description": "正文 UTF-16 code unit 的结束偏移，不包含。" } }, "additionalProperties": false, "description": "结构化 token 在来源正文中的半开区间；服务端校验 start < end 且与正文匹配。" } }, "additionalProperties": false, "description": "picker 生成的结构化 Agent token；聊天中为非执行引用，看板中可由来源 owner 形成 Mention。" }, "description": "非执行 Agent 引用。" }, "mentionOccurrences": { "type": "array", "items": { "type": "object", "required": [ "occurrence_id", "target", "range" ], "properties": { "occurrence_id": { "type": "string", "minLength": 8, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "description": "客户端生成、在一次来源 revision 内稳定的 occurrence ID；同一 Agent 可出现多次。" }, "target": { "type": "object", "required": [ "agent_id", "display_name_snapshot" ], "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "description": "目标 Agent 的稳定语义 ID；仅允许 ASCII 字母、数字、下划线和连字符。" }, "display_name_snapshot": { "type": "string", "minLength": 1, "description": "服务端按 agent_id 从可信 Agent Registry 重建的显示快照；客户端同名字段只用于提交时 range 校验，不参与身份或 system prompt。" } }, "additionalProperties": false, "description": "稳定 Agent 引用；是否执行由来源契约决定，显示名不能单独触发投递。" }, "range": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "integer", "minimum": 0, "description": "正文 UTF-16 code unit 的起始偏移，包含。" }, "end": { "type": "integer", "minimum": 1, "description": "正文 UTF-16 code unit 的结束偏移，不包含。" } }, "additionalProperties": false, "description": "结构化 token 在来源正文中的半开区间；服务端校验 start < end 且与正文匹配。" } }, "additionalProperties": false, "description": "picker 生成的结构化 Agent token；聊天中为非执行引用，看板中可由来源 owner 形成 Mention。" }, "description": "Retired execution input; the HTTP route rejects this field. Use non-executable agentReferences.", "deprecated": true }, "mentionRecipientRequests": { "type": "array", "items": { "type": "object", "required": [ "occurrence_ids", "recipient_agent_id", "route" ], "properties": { "occurrence_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 8, "maxLength": 256 }, "description": "同一来源 revision 中指向该 recipient 的全部 occurrence IDs；只产生一个 delivery。" }, "recipient_agent_id": { "type": "string", "minLength": 1, "description": "必须与 occurrence.target.agent_id 一致的稳定 Agent ID。" }, "route": { "type": "string", "enum": [ "current_conversation", "external_agent" ], "description": "当前 Agent 走普通 conversation；非当前 Agent 走独立 Mention delivery。" }, "context_selection": { "allOf": [ { "type": "object", "required": [ "context_mode", "origin" ], "properties": { "context_mode": { "type": "string", "enum": [ "continue", "isolated", "fork" ], "description": "必填且无默认值：continue=继续明确存在的同一任务上下文；isolated=不同新任务；fork=同一任务有意分叉。" }, "origin": { "type": "string", "enum": [ "delegate", "mention", "task", "workflow", "schedule", "webhook", "decision", "legacy" ] }, "work_context_id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "continue 必填：要继续的稳定 Work Context ID；禁止回退到目标 Agent 最近一次会话。" }, "source_work_context_id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "fork 必填：有意分叉的来源 Work Context ID。" }, "task_ref": { "type": "object", "required": [ "board_id", "task_id" ], "properties": { "board_id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1, "description": "TaskBoard 内稳定 Task ID。" }, "task_version": { "type": "integer", "minimum": 1, "description": "选择时观察到的 Task 版本快照；身份查重只使用 board_id + task_id。" } }, "additionalProperties": false }, "intent_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "context_reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "isolated/fork 必填：说明为何这是不同新任务或为何允许对同一 Task 有意分叉。" } }, "allOf": [ { "if": { "properties": { "context_mode": { "const": "continue" } }, "required": [ "context_mode" ] }, "then": { "required": [ "work_context_id" ], "not": { "anyOf": [ { "required": [ "source_work_context_id" ] }, { "required": [ "intent_id" ] } ] } } }, { "if": { "properties": { "context_mode": { "const": "isolated" } }, "required": [ "context_mode" ] }, "then": { "required": [ "context_reason" ], "anyOf": [ { "required": [ "task_ref" ] }, { "required": [ "intent_id" ] } ], "not": { "anyOf": [ { "required": [ "work_context_id" ] }, { "required": [ "source_work_context_id" ] } ] } } }, { "if": { "properties": { "context_mode": { "const": "fork" } }, "required": [ "context_mode" ] }, "then": { "required": [ "source_work_context_id", "task_ref", "context_reason" ], "not": { "anyOf": [ { "required": [ "work_context_id" ] }, { "required": [ "intent_id" ] } ] } } } ], "additionalProperties": false, "description": "一次执行如何选择 Work Context；调用方必须显式提交，系统只能推荐不能代填。" }, { "type": "object", "required": [ "origin" ], "properties": { "origin": { "type": "string", "const": "mention", "description": "Mention 外部投递只能创建 origin=mention 的 Work Context lineage。" } } } ], "description": "非当前 recipient 单独提交的显式 Work Context selection；没有默认模式。" }, "retry_of_delivery_id": { "type": "string", "minLength": 1, "description": "用户显式重新呼叫时引用旧 delivery；普通传输重试不得填写。" } }, "allOf": [ { "if": { "properties": { "route": { "const": "current_conversation" } }, "required": [ "route" ] }, "then": { "not": { "anyOf": [ { "required": [ "context_selection" ] }, { "required": [ "retry_of_delivery_id" ] } ] } } }, { "if": { "properties": { "route": { "const": "external_agent" } }, "required": [ "route" ] }, "then": { "required": [ "context_selection" ] } } ], "additionalProperties": false, "description": "每个唯一 recipient 的确定性路由；多个显示 occurrence 共用一套显式 selection。" }, "description": "Retired execution input; the HTTP route rejects this field.", "deprecated": true }, "mediaRefs": { "type": "array", "items": { "type": "object", "required": [ "type", "mediaId", "name", "mimeType", "size" ], "properties": { "type": { "type": "string", "description": "媒体业务类型。" }, "mediaId": { "type": "string", "description": "媒体存储引用。" }, "name": { "type": "string", "description": "原始文件名。" }, "mimeType": { "type": "string", "description": "媒体 MIME 类型。" }, "size": { "type": "number", "description": "媒体字节数。" } }, "additionalProperties": true }, "description": "本轮媒体附件引用。" }, "images": { "type": "array", "items": { "type": "object", "required": [ "data", "mimeType" ], "properties": { "data": { "type": "string", "description": "已废弃 Base64 图片数据。" }, "mimeType": { "type": "string", "description": "图片 MIME 类型。" } }, "additionalProperties": false }, "description": "已废弃内联图片附件。" }, "clientRequestId": { "type": "string", "description": "客户端一次提交及其传输重试的稳定 ID。" }, "userMessageId": { "type": "string" }, "requestDigest": { "type": "string", "maxLength": 128, "description": "Optional digest produced by the shared request-body algorithm. The service recomputes it to reject reuse of a request ID with a changed business body." }, "originSocketId": { "type": "string", "description": "Current connected Socket.IO socket.id for precise event delivery; HTTP and Socket authentication must identify the same principal." }, "uiContextAdmission": { "type": "object", "required": [ "version", "admissionRef" ], "properties": { "version": { "type": "integer", "const": 1, "description": "Version of the durable UI context admission-reference envelope." }, "admissionRef": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^ui_admission_[A-Za-z0-9_-]{43}$", "description": "Opaque durable reference to an immutable admitted turn-context sidecar; it contains no snapshot, token, host identity, path, URL, or user text." } }, "additionalProperties": false, "description": "A valid context admission reference from an authorized UI flow. Ordinary standalone scripts omit it." }, "appWorkAdmissionRef": { "type": "string", "pattern": "^apa_[A-Za-z0-9_-]{43}$", "maxLength": 512, "description": "Opaque reference supplied by an authorized application proposal flow. Standalone integration examples omit it; an arbitrary reference does not grant authority." } }, "definitions": { "conversationContentBlock": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "tool_use", "tool_result", "image", "thinking" ], "description": "结构化历史内容块类型。" }, "text": { "type": "string", "description": "文本块正文。" }, "id": { "type": "string", "description": "tool_use 块 ID。" }, "name": { "type": "string", "description": "工具名称。" }, "input": { "description": "工具输入 JSON。" }, "tool_use_id": { "type": "string", "description": "tool_result 对应的 tool_use ID。" }, "content": { "description": "工具结果文本或嵌套结构化内容块。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/QueryStartRequest/definitions/conversationContentBlock" } } ] }, "is_error": { "type": "boolean", "description": "工具结果是否表示错误。" }, "source": { "type": "object", "required": [ "type", "media_type", "data" ], "properties": { "type": { "const": "base64", "description": "图片数据编码类型。" }, "media_type": { "type": "string", "description": "图片 MIME 类型。" }, "data": { "type": "string", "description": "Base64 图片数据。" } }, "additionalProperties": false }, "thinking": { "type": "string", "description": "Provider thinking 正文。" } }, "additionalProperties": false, "description": "Query conversationHistory 中的结构化内容块。" }, "conversationMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ], "description": "消息角色；system 仅用于受控上下文边界 marker。" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/QueryStartRequest/definitions/conversationContentBlock" }, "description": "结构化消息内容。" }, "timestamp": { "type": "number", "description": "消息时间戳（毫秒）。" }, "id": { "type": "string", "description": "SessionMessage 空间中的稳定消息 ID。" }, "compactCutoff": { "type": "boolean", "description": "压缩摘要边界 marker。" }, "summarizedCount": { "type": "number", "description": "本次摘要覆盖的消息数。" }, "compactedAt": { "type": "string", "format": "date-time", "description": "压缩发生时间。" }, "compactAnchorMessageId": { "type": "string", "description": "压缩后保留区第一条消息 ID。" }, "compactKeptTurns": { "type": "number", "description": "压缩后保留的对话轮数。" }, "compactCoverStartMessageId": { "type": "string", "description": "本 marker 覆盖区第一条消息 ID。" }, "compactRunId": { "type": "string", "description": "老 marker 的覆盖 run。" }, "compactMerged": { "type": "boolean", "description": "是否为摘要链二级合并产物。" }, "compactSupersedes": { "type": "array", "items": { "type": "string" }, "description": "被本 marker 取代的 marker ID 列表。" }, "compactTrigger": { "type": "string", "enum": [ "auto", "manual" ], "description": "压缩由自动阈值还是用户显式触发。" }, "compactWindow": { "type": "number", "description": "生成自动压缩 marker 时的有效上下文窗口。" }, "contextReset": { "type": "boolean", "description": "不携带摘要的显式遗忘边界。" }, "resetAnchorMessageId": { "type": "string", "description": "触发 reset 的 user 消息 ID。" }, "resetReason": { "type": "string", "description": "reset 的用户可见原因。" }, "fileReferences": { "type": "array", "items": { "type": "string" }, "description": "用户引用的文件路径。" }, "mediaRefs": { "type": "array", "items": { "type": "object", "required": [ "mediaId" ], "properties": { "mediaId": { "type": "string", "description": "媒体存储中的稳定引用。" }, "mimeType": { "type": "string", "description": "媒体 MIME 类型。" }, "type": { "type": "string", "description": "媒体业务类型。" } }, "additionalProperties": false }, "description": "历史消息引用的媒体。" } }, "additionalProperties": false } }, "additionalProperties": false, "not": { "anyOf": [ { "required": [ "mentionOccurrences" ] }, { "required": [ "mentionRecipientRequests" ] } ] } }, "QueryAdmission": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "description": "请求是否已被准入。" }, "clientRequestId": { "type": "string", "description": "对应的客户端请求 ID。" }, "duplicate": { "type": "boolean", "description": "是否命中幂等重复请求。" }, "busy": { "type": "boolean", "description": "准入被竞争挡下而非失败，仅两种来源：会话清除窗口（query:start、HTTP start、follow-up；清除结束后可用同一 clientRequestId 重试）与同一 session 已有 continue 在执行（仅 query:continue）。start 准入只有清除窗口会置位，客户端据此区分清除与其它 retryable 拒绝；缺省或 false 不代表清除。" }, "error": { "type": "string", "description": "拒绝时的稳定错误说明。" }, "code": { "type": "string", "description": "稳定拒绝码，如 CLIENT_REQUEST_BODY_MISMATCH（同 ID 不同请求体，不可重试）。" }, "retryable": { "type": "boolean", "description": "是否允许用同一 clientRequestId 重试。" }, "uiContextFaultCode": { "type": "string", "enum": [ "snapshot_missing", "snapshot_stale", "surface_mismatch", "auth_required", "human_required", "redaction_blocked", "adapter_invalid", "snapshot_conflict", "protocol_unsupported", "host_unavailable", "action_unavailable", "action_failed", "action_outcome_unknown", "action_capacity_exceeded" ], "description": "Stable fail-closed UI context protocol fault code." }, "sessionId": { "type": "string", "description": "已建立或已存在的 session ID。" } }, "additionalProperties": false, "description": "Socket.IO query:start 与 HTTP start 的准入响应。" }, "QueryFollowUpRequest": { "type": "object", "required": [ "sessionId", "originSocketId", "message" ], "properties": { "sessionId": { "type": "string" }, "originSocketId": { "type": "string", "minLength": 1, "description": "Current connected socket.id, authenticated as the same principal as the HTTP request." }, "message": { "type": "object", "required": [ "role", "content" ], "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "timestamp": { "type": "number" } }, "additionalProperties": true }, "clientRequestId": { "type": "string" }, "requestDigest": { "type": "string" }, "mediaRefs": { "type": "array", "items": { "type": "object", "required": [ "type", "mediaId", "name", "mimeType", "size" ], "properties": { "type": { "type": "string", "description": "媒体业务类型。" }, "mediaId": { "type": "string", "description": "媒体存储引用。" }, "name": { "type": "string", "description": "原始文件名。" }, "mimeType": { "type": "string", "description": "媒体 MIME 类型。" }, "size": { "type": "number", "description": "媒体字节数。" } }, "additionalProperties": true }, "description": "本轮媒体附件引用。" }, "images": { "type": "array", "items": { "type": "object", "required": [ "data", "mimeType" ], "properties": { "data": { "type": "string", "description": "已废弃 Base64 图片数据。" }, "mimeType": { "type": "string", "description": "图片 MIME 类型。" } }, "additionalProperties": false }, "description": "已废弃内联图片附件。" }, "fileReferences": { "type": "array", "items": { "type": "string" } }, "activeDocPath": { "type": "string" }, "reasoning": { "type": "string" }, "agentReferences": { "type": "array", "items": { "type": "object", "required": [ "occurrence_id", "target", "range" ], "properties": { "occurrence_id": { "type": "string", "minLength": 8, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "description": "客户端生成、在一次来源 revision 内稳定的 occurrence ID；同一 Agent 可出现多次。" }, "target": { "type": "object", "required": [ "agent_id", "display_name_snapshot" ], "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "description": "目标 Agent 的稳定语义 ID；仅允许 ASCII 字母、数字、下划线和连字符。" }, "display_name_snapshot": { "type": "string", "minLength": 1, "description": "服务端按 agent_id 从可信 Agent Registry 重建的显示快照；客户端同名字段只用于提交时 range 校验，不参与身份或 system prompt。" } }, "additionalProperties": false, "description": "稳定 Agent 引用；是否执行由来源契约决定，显示名不能单独触发投递。" }, "range": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "integer", "minimum": 0, "description": "正文 UTF-16 code unit 的起始偏移，包含。" }, "end": { "type": "integer", "minimum": 1, "description": "正文 UTF-16 code unit 的结束偏移，不包含。" } }, "additionalProperties": false, "description": "结构化 token 在来源正文中的半开区间；服务端校验 start < end 且与正文匹配。" } }, "additionalProperties": false, "description": "picker 生成的结构化 Agent token；聊天中为非执行引用，看板中可由来源 owner 形成 Mention。" }, "description": "非执行 Agent 引用。" }, "uiContextAdmission": { "type": "object", "required": [ "version", "admissionRef" ], "properties": { "version": { "type": "integer", "const": 1, "description": "Version of the durable UI context admission-reference envelope." }, "admissionRef": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^ui_admission_[A-Za-z0-9_-]{43}$", "description": "Opaque durable reference to an immutable admitted turn-context sidecar; it contains no snapshot, token, host identity, path, URL, or user text." } }, "additionalProperties": false, "description": "Only UI context object allowed on an actual query or pending record; omitting the entire field preserves the legacy no-context path." } }, "additionalProperties": true, "description": "Documented request subset from the route interface. Additional fields do not imply authorization or guaranteed support.", "not": { "anyOf": [ { "required": [ "mentionOccurrences" ] }, { "required": [ "mentionRecipientRequests" ] } ] } }, "ClientRequestLookupRequest": { "type": "object", "additionalProperties": false, "required": [ "agentId", "requests" ], "description": "按 clientRequestId 只读查询服务端接纳状态；不占位、不清理、不产生任何副作用。", "properties": { "agentId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" }, "requests": { "type": "array", "minItems": 1, "maxItems": 100, "description": "要查询的提交列表，每项一个 clientRequestId。", "items": { "type": "object", "additionalProperties": false, "required": [ "clientRequestId" ], "properties": { "clientRequestId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S", "description": "客户端一次提交及其全部重发共用的稳定 ID。" }, "userMessageId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" } } } } } }, "ClientRequestLookupResponse": { "type": "object", "additionalProperties": false, "required": [ "protocolVersion", "serverInstanceId", "observedAt", "autoReplayRetentionMs", "tombstoneRetentionMs", "results" ], "description": "只读接纳查询结果。", "properties": { "protocolVersion": { "type": "integer", "const": 1, "description": "查询协议版本。" }, "serverInstanceId": { "type": "string", "description": "当前 Agent Service 进程代际 ID；与恢复快照同源，重启即变化。" }, "observedAt": { "type": "string", "format": "date-time", "description": "服务端观察时刻（ISO 8601），客户端用于抵御本地墙钟回拨。" }, "autoReplayRetentionMs": { "type": "integer", "minimum": 0, "description": "客户端同 ID 自动重放窗口（毫秒）。" }, "tombstoneRetentionMs": { "type": "integer", "minimum": 0, "description": "服务端幂等 tombstone 保护窗口（毫秒）；超出后查询结论不可信。" }, "results": { "type": "array", "description": "与请求一一对应（按 clientRequestId）。", "items": { "type": "object", "additionalProperties": false, "required": [ "clientRequestId", "status" ], "properties": { "clientRequestId": { "type": "string", "description": "被查询的 clientRequestId。" }, "status": { "type": "string", "enum": [ "committed", "reserved", "absent", "unknown" ], "description": "committed=已持久提交（至多一次，原 ID 不会再执行）；reserved=当前服务进程内占位中（排队或正在做提交前复检）；absent=截至此刻既无提交也无占位（原请求可能仍在路上，必须同 ID 重发由服务端裁决）；unknown=无法判定（旧版无作用域记录、存储不可读或注册表 fail closed）。" }, "committedAt": { "type": "string", "format": "date-time", "description": "status=committed 时的持久提交时刻。" }, "sessionId": { "type": "string" }, "committedServerInstance": { "type": "string", "enum": [ "current", "previous", "unknown" ] }, "executionWitness": { "type": "string", "enum": [ "user-message", "none", "unknown" ], "description": "user-message=磁盘已有该提交的用户消息（执行过）；none=没有；unknown=无法查证（缺 userMessageId 或存储不可读）。" } } } } } }, "WebhookManagement": { "type": "object", "required": [ "enabled", "hasSecret", "events", "availableTools" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "hasSecret": { "type": "boolean", "description": "是否已有非空 secret；读取不返回其值。" }, "events": { "type": "array", "items": { "type": "object", "required": [ "event", "promptTemplate", "maxTurns", "toolIds" ], "additionalProperties": false, "properties": { "event": { "type": "string" }, "promptTemplate": { "type": "string" }, "maxTurns": { "type": "number" }, "toolIds": { "type": "array", "items": { "type": "string" } } } } }, "availableTools": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "riskLevel", "requiresConfirmation" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high" ] }, "requiresConfirmation": { "type": "boolean" } } } } } }, "WebhookEventWrite": { "type": "object", "required": [ "promptTemplate", "toolIds" ], "properties": { "promptTemplate": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "\\S", "description": "事件提示模板，{{key}} 从 payload 的顶层字段取值。" }, "toolIds": { "type": "array", "maxItems": 512, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "从管理读取返回的 availableTools 中选择工具 ID；空数组表示不授权任何工具。" }, "maxTurns": { "type": "integer", "minimum": 1, "maximum": 100, "description": "事件最多执行的模型轮次数，省略时为 5。", "default": 5 } }, "additionalProperties": false }, "WebhookEventWritten": { "type": "object", "required": [ "success", "event", "enabled" ], "additionalProperties": false, "properties": { "success": { "const": true }, "event": { "type": "string" }, "enabled": { "const": true }, "secret": { "type": "string", "description": "仅在本次首次生成 secret 时返回；保存修改已有事件不会再次返回。" } } }, "WebhookEnabledRequest": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "开启或暂停该智能体已有 Webhook 事件。" } } }, "WebhookEnabledResponse": { "type": "object", "required": [ "success", "enabled" ], "additionalProperties": false, "properties": { "success": { "const": true }, "enabled": { "type": "boolean" } } }, "WebhookSecretRotation": { "type": "object", "required": [ "secret" ], "additionalProperties": false, "properties": { "secret": { "type": "string", "minLength": 43, "maxLength": 43 } } }, "ManagementError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "details": { "type": "array", "items": {} } }, "additionalProperties": false }, "ScheduleMessage": { "type": "object", "additionalProperties": false, "description": "完整的可见调度消息契约；授权快照、正文、附件引用和收件人均接受运行时验证。", "required": [ "id", "scheduleId", "authorizationScope", "text", "isError", "timestamp" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "可信结果路由给出的稳定、非授权标识。" }, "recipientUserId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "可信结果路由给出的稳定、非授权标识。" }, "origin": { "enum": [ "schedule", "webhook" ], "description": "旧记录未声明时按 schedule 显示。" }, "scheduleId": { "type": "string", "description": "所属调度标识；不是执行授权。" }, "occurrenceId": { "type": "string", "description": "结果所属稳定发生标识，不能单凭它重新执行。" }, "authorizationScope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "const": "agent", "description": "Agent 作用域；结果还需精确收件人校验。" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "boardId", "bindingId" ], "properties": { "kind": { "const": "taskboard", "description": "保持原 TaskBoard 来源 ACL，不能退化为普通 Agent 作用域。" }, "boardId": { "type": "string", "description": "来源 TaskBoard 标识。" }, "bindingId": { "type": "string", "description": "冻结的资源绑定标识。" } } } ], "description": "不可变来源授权快照；读取和清除都重新核验当前权限。" }, "displayName": { "type": "string", "description": "可选任务显示名。" }, "text": { "type": "string", "description": "受存储边界截断的可见摘要，不是执行指令。" }, "isError": { "type": "boolean", "description": "是否为失败结果；不会改变脚本真实终态。" }, "timestamp": { "type": "number", "description": "冻结的原交付时间，重放不得使用当前时间替换。" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "message", "status", "sentAt" ], "description": "既有 SendUserMessage 用户交付形状，仅保存附件引用。", "properties": { "message": { "type": "string", "description": "受存储边界截断的用户交付正文。" }, "status": { "enum": [ "normal", "proactive" ], "description": "普通回复或主动告知。" }, "sentAt": { "type": "string", "description": "工具侧原交付时刻。" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "附件解析降级告警。" }, "attachments": { "type": "array", "description": "引用型附件，不存二进制正文。", "items": { "type": "object", "additionalProperties": false, "required": [ "path", "name", "mimeType", "size", "isImage" ], "properties": { "path": { "type": "string", "description": "已解析的附件路径，读取仍受资源准入限制。" }, "name": { "type": "string", "description": "附件文件名。" }, "mimeType": { "type": "string", "description": "附件 MIME 类型。" }, "size": { "type": "number", "description": "附件字节数。" }, "isImage": { "type": "boolean", "description": "是否为图片。" }, "mediaId": { "type": "string", "description": "可选媒体存储引用。" }, "width": { "type": "number", "description": "可选图片宽度。" }, "height": { "type": "number", "description": "可选图片高度。" } } } } } } } }, "ScheduleMessagePage": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleMessage" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } } }, "x-service": "agent-service", "x-source": { "repository": "desirecore/desirecore", "revision": "e45f22902af2dc45b109cfa8f454795538aea2ed" } }