From 1be39dc8378fbfd828f01c5440a4f8ec2fe244a5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:32:00 +0000 Subject: [PATCH 1/2] Sync agent API spec Source ref: cf90f4d0ee5de3f47b5434a52bccbf096b608e04 Source commit: cf90f4d0ee5de3f47b5434a52bccbf096b608e04 --- developers/agent-api-openapi.yaml | 457 ++++++++++++++++++++++++++++-- 1 file changed, 432 insertions(+), 25 deletions(-) diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index 89b08a07a..884c723fa 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,4 +1,29 @@ paths: + /networking/policies: + get: + summary: List built-in network policies + description: | + Return Warp-managed network policies grouped by name, with every published + version and its included allowed hosts. Use a name and version in networkPolicy.extends. + Policies do not include the platform's system-required egress rules. + operationId: listNetworkPolicies + tags: + - networking + security: + - bearerAuth: [] + responses: + '200': + description: 'Built-in policies sorted by name, with versions sorted lexicographically' + content: + application/json: + schema: + $ref: '#/components/schemas/ListNetworkPoliciesResponse' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' /networking/egress-ranges: get: summary: List Warp-hosted agent egress ranges @@ -557,6 +582,53 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' + '/factory/{uid}/blueprint-proposal': + post: + summary: Generate a blueprint proposal for a factory + description: | + Starts an agent run that proposes a blueprint, as a pull request, for a + factory that does not yet have one. + operationId: startFactoryBlueprintProposal + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + responses: + '201': + description: Blueprint proposal run started + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryRunResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Factory not found or not accessible + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: 'The factory already has a blueprint, or has no foreman agent to run the proposal' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' '/factory/{uid}/runs': post: summary: Dispatch a run to a factory @@ -2318,6 +2390,54 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /agent/runs/batch-get: + post: + summary: Get multiple runs by ID + description: | + Retrieve run details for 1–100 run IDs. Returns a top-level array in + input order, preserving duplicates with one result per input occurrence. + Each result contains the requested run_id and exactly one of `run`, the + same run object returned by getRun, or `error`, the standard API error + getRun would return for that ID. Authorization and per-run errors + follow getRun semantics. Completed batches return HTTP 200 even when + every result is an error; shared infrastructure failures fail the + request with HTTP 500. + operationId: batchGetRuns + tags: + - agent + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BatchGetRunsRequest' + responses: + '200': + description: One run or error per requested ID + content: + application/json: + schema: + $ref: '#/components/schemas/BatchGetRunsResponse' + '400': + description: Malformed body or invalid run_ids list + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' '/agent/runs/{runId}': get: summary: Get run details @@ -2336,6 +2456,12 @@ paths: required: true schema: type: string + - name: include_diagnostics + in: query + description: Include diagnostic messages for this run. + schema: + type: boolean + default: false responses: '200': description: Run details @@ -2415,6 +2541,53 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + '/agent/runs/{runId}/diagnostics': + get: + summary: Get run diagnostics + description: Retrieve diagnostics recorded for an agent run. + operationId: getRunDiagnostics + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string + responses: + '200': + description: Run diagnostics + content: + application/json: + schema: + $ref: '#/components/schemas/GetRunDiagnosticsResponse' + '400': + description: Missing run ID + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to access run + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' '/agent/runs/{runId}/conversation': get: summary: Get normalized run conversation @@ -2434,6 +2607,21 @@ paths: required: true schema: type: string + - name: scope + in: query + description: | + Portion of the conversation to return. `full` returns the entire + conversation. `final_message` returns only the text of the last + assistant message after the most recent user message, as a single + root step with one message; `steps` is empty when that turn has no + assistant text yet. + required: false + schema: + type: string + enum: + - full + - final_message + default: full responses: '200': description: Normalized conversation @@ -2442,7 +2630,7 @@ paths: schema: $ref: '#/components/schemas/ConversationResponse' '400': - description: Missing run ID + description: Missing run ID or invalid scope content: application/json: schema: @@ -5603,6 +5791,64 @@ paths: $ref: '#/components/schemas/Error' components: schemas: + BuiltinNetworkPolicy: + type: object + description: One published Warp-managed network policy version. + required: + - name + - version + - allowed_hosts + - is_latest + properties: + name: + type: string + examples: + - warp/package-registries + version: + type: string + description: Exact semantic version. + examples: + - 1.0.0 + allowed_hosts: + type: array + items: + type: string + description: Literal hosts granted by this policy version. + is_latest: + type: boolean + description: Whether this is the highest stable version selected by the latest alias. + BuiltinNetworkPolicyGroup: + type: object + description: A Warp-managed network policy and its published versions. + required: + - name + - latest_version + - versions + properties: + name: + type: string + examples: + - warp/package-registries + latest_version: + type: + - string + - 'null' + description: 'Highest stable version selected by the latest alias, or null if none exists.' + examples: + - 1.0.0 + versions: + type: array + items: + $ref: '#/components/schemas/BuiltinNetworkPolicy' + ListNetworkPoliciesResponse: + type: object + required: + - policies + properties: + policies: + type: array + items: + $ref: '#/components/schemas/BuiltinNetworkPolicyGroup' EgressRangesResponse: type: object required: @@ -5722,8 +5968,8 @@ components: items: $ref: '#/components/schemas/FactoryCodeForge' description: | - Effective source-control providers for the factory. When the - effective set is empty, this contains the primary code_forge. + Enabled source-control providers for the factory. Empty when the + factory has no enabled forge; never contains NONE. repositories: type: array items: @@ -5763,6 +6009,19 @@ components: Default credential strategy for runs executed by the factory's named agents. Always a concrete value; factories default to EXECUTOR unless explicitly set to CREATOR. + restrict_followups_to_starter: + type: boolean + description: | + When true, only the Warp user who started a run may send it + follow-ups. Senders on Slack, GitHub, Linear and other + integrations are matched to Warp users through their linked + accounts; follow-ups from agents and the system are unaffected. + allow_service_account_followups: + type: boolean + description: | + When true, follow-ups sent with a service account's API key are + accepted even though restrict_followups_to_starter is true. Has + no effect while restrict_followups_to_starter is false. integrations: type: - array @@ -6108,8 +6367,10 @@ components: allOf: - $ref: '#/components/schemas/FactoryRepositoryCodeForge' description: | - The concrete forge hosting this repository. Omitted means the - factory's primary code_forge. + The concrete forge hosting this repository. Always present in + responses. On update it may be omitted only when the factory has + exactly one enabled code forge, which it then defaults to; on + create, omission means the factory's code_forge. provider_metadata: type: object additionalProperties: @@ -8358,6 +8619,50 @@ components: `X-Warp-Team-Uid` header, or the API key's team. Null when a user request has no team selected and the list spans every team the user belongs to. + BatchGetRunsRequest: + type: object + required: + - run_ids + properties: + run_ids: + type: array + minItems: 1 + maxItems: 100 + items: + type: string + minLength: 1 + description: 'Run IDs to retrieve, in result order. Duplicates are preserved.' + BatchGetRunsResponse: + type: array + items: + $ref: '#/components/schemas/BatchGetRunResult' + BatchGetRunResult: + description: Result for one requested run ID. Exactly one of `run` or `error` is present. + oneOf: + - $ref: '#/components/schemas/BatchGetRunSuccess' + - $ref: '#/components/schemas/BatchGetRunError' + BatchGetRunSuccess: + type: object + required: + - run_id + - run + properties: + run_id: + type: string + description: 'Requested run ID, echoed from the request.' + run: + $ref: '#/components/schemas/RunItem' + BatchGetRunError: + type: object + required: + - run_id + - error + properties: + run_id: + type: string + description: 'Requested run ID, echoed from the request.' + error: + $ref: '#/components/schemas/Error' RunItem: type: object required: @@ -8483,6 +8788,11 @@ components: items: $ref: '#/components/schemas/ArtifactItem' description: 'Artifacts created during the run (plans, pull requests, etc.)' + diagnostics: + type: array + items: + $ref: '#/components/schemas/RunDiagnostic' + description: 'Diagnostics for this run, only included on request.' agent_skill: $ref: '#/components/schemas/AgentSkill' scope: @@ -8497,6 +8807,37 @@ components: type: array items: $ref: '#/components/schemas/AIRunTimelineEvent' + GetRunDiagnosticsResponse: + type: object + description: Response body for listing diagnostics recorded for a run. + required: + - diagnostics + properties: + diagnostics: + type: array + items: + $ref: '#/components/schemas/RunDiagnostic' + RunDiagnostic: + type: object + description: A diagnostic recorded for an agent run. Diagnostics are non-fatal warnings and informational messages about the run. + required: + - message + - code + properties: + message: + type: string + code: + type: string + data: + type: object + additionalProperties: true + timestamp: + type: string + format: date-time + created_at: + type: string + format: date-time + description: When the diagnostic was recorded. AIRunTimelineEvent: type: object description: A setup or lifecycle event recorded for an agent run. @@ -9070,6 +9411,13 @@ components: description: | What the run's platform usage was billed at, in US dollars. Runs that predate billed-amount tracking fall back to an estimated cost. + platform_duration_seconds: + type: number + format: double + minimum: 0 + description: | + Recorded billable platform runtime for this run, in seconds. + Omitted when unavailable; zero when recorded as zero. total_tokens: type: integer format: int64 @@ -9365,9 +9713,10 @@ components: - LOCAL - REMOTE description: | - Where the run executed: - - LOCAL: Executed in the user's local Warp environment - - REMOTE: Executed by a remote/cloud worker + Execution location of the run's latest execution, including ended executions: + - LOCAL: The latest execution is assigned to the machine running Warp or Oz, or to the same process as its cloud parent. + - REMOTE: The latest execution is remote or unassigned, or the run has no executions. + This is not a liveness indicator. A newer execution can change the classification; the task's legacy worker assignment is ignored. AmbientAgentConfig: type: object description: Configuration for a cloud agent run @@ -10990,7 +11339,8 @@ components: enum: - all_agents - selected_agents - description: Whether the scorer applies to every factory agent or selected agents + - selected_stages + description: 'Whether the scorer applies to every factory agent, selected agents, or selected blueprint stages' agent_uids: type: array description: | @@ -11004,9 +11354,20 @@ components: description: | Selected agents and their evidence policy. Required and non-empty for selected_agents when agent_uids is omitted; must be empty for - all_agents and cannot be combined with agent_uids. + all_agents or selected_stages and cannot be combined with agent_uids. items: $ref: '#/components/schemas/ScorerAgentInput' + stages: + type: array + minItems: 1 + uniqueItems: true + description: | + Blueprint stage names. Required for selected_stages and mutually + exclusive with agent_uids and agents. Available only for blueprint + factories. + items: + type: string + minLength: 1 sampling_rate: type: - number @@ -11098,9 +11459,10 @@ components: enum: - all_agents - selected_agents + - selected_stages description: | New scope mode. Defaults to the scorer's current mode when only - agent_uids or agents is supplied. + agent_uids, agents, or stages is supplied. agent_uids: type: array description: | @@ -11115,10 +11477,21 @@ components: description: | Complete replacement selected-agent configuration. Required and non-empty when the resulting scope_mode is selected_agents and - agent_uids is omitted; must be empty for all_agents and cannot be - combined with agent_uids. + agent_uids is omitted; must be empty for all_agents or selected_stages + and cannot be combined with agent_uids. items: $ref: '#/components/schemas/ScorerAgentInput' + stages: + type: array + minItems: 1 + uniqueItems: true + description: | + Complete replacement blueprint stage membership. Required when the + resulting scope_mode is selected_stages and mutually exclusive with + agent_uids and agents. Available only for blueprint factories. + items: + type: string + minLength: 1 model_id: type: string minLength: 1 @@ -11162,6 +11535,7 @@ components: - self_improvement_enabled - scorer_kind - scope_mode + - stages - agent_uids - agents - sampling_rate @@ -11205,15 +11579,21 @@ components: enum: - all_agents - selected_agents - description: Whether the scorer applies to every factory agent or selected agents + - selected_stages + description: 'Whether the scorer applies to every factory agent, selected agents, or selected blueprint stages' + stages: + type: array + items: + type: string + description: Blueprint stage names the scorer applies to; empty unless scope_mode is selected_stages agent_uids: type: array - description: Agents attached to a selected_agents scorer; empty for all_agents + description: Agents attached to the scorer; empty unless scope_mode is selected_agents items: type: string agents: type: array - description: Selected agents and whether each evaluation includes its run descendants + description: Selected agents and whether each evaluation includes its run descendants; empty unless scope_mode is selected_agents items: $ref: '#/components/schemas/ScorerAgentInput' sampling_rate: @@ -11277,6 +11657,7 @@ components: - allowed_classifications - threshold - scope_mode + - stages - agents - scorer_kind - sampling_rate @@ -11317,12 +11698,18 @@ components: enum: - all_agents - selected_agents - description: all_agents (every agent in the scorer's factory) or selected_agents + - selected_stages + description: 'Whether the scorer applies to every factory agent, selected agents, or selected blueprint stages' + stages: + type: array + items: + type: string + description: Blueprint stage names the scorer applies to; empty unless scope_mode is selected_stages agents: type: array items: $ref: '#/components/schemas/ScorerScopeAgent' - description: Named agents in scope; empty when the scorer covers all factory agents + description: Named agents in scope; empty unless scope_mode is selected_agents scorer_kind: $ref: '#/components/schemas/ScorerKind' sampling_rate: @@ -11411,7 +11798,10 @@ components: properties: run_id: type: string - description: The selected agent run that anchors the scoring attempt + description: 'The scored run; for a stage scorer, the Factory task''s top-level run' + stage_name: + type: string + description: Blueprint stage this attempt evaluates; present only for stage scorers conversation_id: type: - string @@ -11704,6 +12094,9 @@ components: scorer_name: type: string description: Display name of the evaluation + stage_name: + type: string + description: Blueprint stage this attempt evaluates; present only for stage scorers attempt_status: $ref: '#/components/schemas/RunScoreAttemptStatus' is_in_flight: @@ -11883,8 +12276,7 @@ components: `secrets_append` is an exception: it appends secrets idempotently and must be the only supplied field, including fields supplied as `null`. `network_policy` is also an exception: omission preserves the policy, - null clears it, and an object replaces it wholesale. An object with - no allowed hosts carries deny-all intent. + null clears it, and an object replaces it wholesale. properties: name: type: string @@ -12407,8 +12799,6 @@ components: required: - uid - name - - agent_uid - - factory_agent_type properties: uid: type: string @@ -12418,6 +12808,7 @@ components: type: string agent_uid: type: string + description: 'Agent to benchmark, supplied together with factory_agent_type.' factory_agent_type: type: string tasks: @@ -12517,12 +12908,15 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkRepoRef' + BenchmarkOptionalName: + type: string + maxLength: 200 + description: Optional display name. Surrounding whitespace is trimmed; empty clears the name. BenchmarkConfigurationInput: type: object properties: display_name: - type: string - description: Optional name for this configuration. + $ref: '#/components/schemas/BenchmarkOptionalName' harness: type: string model: @@ -12577,6 +12971,8 @@ components: required: - repetition_count properties: + display_name: + $ref: '#/components/schemas/BenchmarkOptionalName' configurations: type: array description: | @@ -12683,6 +13079,8 @@ components: - execution - scoring properties: + display_name: + $ref: '#/components/schemas/BenchmarkOptionalName' uid: type: string description: 'existing benchmark Run UID, including legacy non-UUID identities.' @@ -13122,6 +13520,9 @@ components: - $ref: '#/components/schemas/BenchmarkTrialScoringState' - type: 'null' description: existing effective ledger status after binding/cutoff checks; null when no ledger row exists. + error_message: + type: string + description: 'retained user-facing scoring failure message, frozen when this pair settled without a score; omitted when unavailable.' BenchmarkTrialResults: type: object required: @@ -13463,6 +13864,9 @@ components: - attempts - judge_runs properties: + status_message: + type: string + description: 'user-facing status message of the Trial''s current execution, when retained.' started_at: type: - string @@ -13521,6 +13925,9 @@ components: agent_run_id: type: string description: judge execution ID retained in the durable dispatch row. + state: + $ref: '#/components/schemas/BenchmarkExecutionState' + description: 'underlying judge execution state, omitted when the execution is no longer retained.' BenchmarkResultsSummary: type: object required: From 6ba6e1734f2ee48181a6253305f5e537d91e7b8d Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 3 Nov 2026 10:58:18 -0800 Subject: [PATCH 2/2] Apply suggestion from @warp-for-oss[bot] Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com> --- developers/agent-api-openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index 884c723fa..f95139b6a 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -4,7 +4,7 @@ paths: summary: List built-in network policies description: | Return Warp-managed network policies grouped by name, with every published - version and its included allowed hosts. Use a name and version in networkPolicy.extends. + version and its included allowed hosts. Use a name and version in network_policy.extends. Policies do not include the platform's system-required egress rules. operationId: listNetworkPolicies tags: