From 8c4bb749f31008c772f8301cfb9288edc2776ce3 Mon Sep 17 00:00:00 2001
From: captainsafia <safia@safia.rocks>
Date: Thu, 28 May 2026 16:41:59 +0000
Subject: [PATCH] docs: expose agent followups endpoint

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 .../references/sync-policy.md                 |  3 +-
 .../sync-openapi-spec/scripts/sync_openapi.py |  6 +-
 developers/agent-api-openapi.yaml             | 81 +++++++++++++++++++
 3 files changed, 86 insertions(+), 4 deletions(-)

diff --git a/.agents/skills/sync-openapi-spec/references/sync-policy.md b/.agents/skills/sync-openapi-spec/references/sync-policy.md
index 51466651..a4fb5d3e 100644
--- a/.agents/skills/sync-openapi-spec/references/sync-policy.md
+++ b/.agents/skills/sync-openapi-spec/references/sync-policy.md
@@ -22,9 +22,8 @@ The `/harness-support/*` endpoints form the worker-to-server contract used by Oz
 
 ## Excluded paths (within otherwise-public tags)
 
-These five `agent`-tag paths are excluded individually because the `agent` tag itself remains public:
+These four `agent`-tag paths are excluded individually because the `agent` tag itself remains public:
 
-- `/agent/runs/{runId}/followups` — internal followup-prompt mechanism used by the harness; not for direct customer use.
 - `/agent/runs/{runId}/handoff/attachments` — handoff plumbing tied to local-to-cloud session handoff.
 - `/agent/handoff/upload-snapshot` — handoff plumbing (snapshot upload from a local worker).
 - `/agent/conversations/{conversation_id}/fork` — conversation-forking primitive used by the harness, not stable public API.
diff --git a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
index f6981e97..345ee5dc 100644
--- a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
+++ b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
@@ -47,7 +47,6 @@
 # the public API reference. Keep in sync with references/sync-policy.md.
 EXCLUDED_PATHS: frozenset[str] = frozenset(
     {
-        "/agent/runs/{runId}/followups",
         "/agent/runs/{runId}/handoff/attachments",
         "/agent/handoff/upload-snapshot",
         "/agent/conversations/{conversation_id}/fork",
@@ -459,7 +458,10 @@ def _self_test() -> int:
 
     out = transform(sample)
     paths = set(out["paths"].keys())
-    assert paths == {"/agent/run"}, f"unexpected paths: {paths}"
+    assert paths == {
+        "/agent/run",
+        "/agent/runs/{runId}/followups",
+    }, f"unexpected paths: {paths}"
 
     schemas = set(out["components"]["schemas"].keys())
     # Config and Mode are reachable transitively (allOf, items)
diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml
index d032b3f5..8c2bec4c 100644
--- a/developers/agent-api-openapi.yaml
+++ b/developers/agent-api-openapi.yaml
@@ -638,6 +638,70 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /agent/runs/{runId}/followups:
+    post:
+      summary: Submit a follow-up message for a run
+      description: |
+        Send a follow-up message to an existing run. The server transparently
+        routes the message based on the current state of the run (still
+        queued, actively running, or ended). A 200 response means the follow-up
+        was accepted; updated run state can be observed via
+        `GET /agent/runs/{runId}`.
+      operationId: submitRunFollowup
+      tags:
+      - agent
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: runId
+        in: path
+        description: The unique identifier of the run
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RunFollowupRequest'
+      responses:
+        '200':
+          description: Follow-up accepted
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          description: Invalid request (empty message, no active sandbox without conversation ID, etc.)
+          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 submit follow-ups for this run
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: Run not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /agent/conversations/{conversation_id}:
     get:
       summary: Get normalized conversation
@@ -3312,6 +3376,23 @@ components:
       - authentication_required
       - resource_unavailable
       - internal_error
+    RunFollowupRequest:
+      type: object
+      description: Request body for submitting a follow-up message to an existing run.
+      required:
+      - message
+      properties:
+        message:
+          type: string
+          x-oapi-codegen-extra-tags:
+            binding: required
+          description: The follow-up message to send to the run.
+        mode:
+          $ref: '#/components/schemas/AgentRunMode'
+          description: |
+            Optional query mode for the follow-up. Defaults to `normal` when
+            omitted. The server does not infer mode from prompt prefixes such
+            as `/plan`.
     ListModelsResponse:
       type: object
       required: