Add run_on_client: agents run commands with files on the user's Macs

api/openapi.yaml

@@ -897,6 +897,43 @@ paths:
               schema: { $ref: "#/components/schemas/InboxItem" }
         "404": { $ref: "#/components/responses/Error" }
 
+  /api/inbox/{itemId}/bundle:
+    parameters:
+      - { name: itemId, in: path, required: true, schema: { type: string } }
+    get:
+      operationId: getRunBundle
+      description: A client_run item's files, as a gzipped tar of its paths relative to the worktree. Served while the item is open.
+      responses:
+        "200":
+          description: The bundle.
+          content:
+            application/gzip: { schema: { type: string, format: binary } }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+
+  /api/inbox/{itemId}/runs:
+    parameters:
+      - { name: itemId, in: path, required: true, schema: { type: string } }
+    post:
+      operationId: reportRun
+      description: >
+        Records one Mac's run of a client_run item as a run response, sent to the agent like an answer.
+        The item stays as it is, so other Macs can run it too; it is accepted after the item closes.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RunReport" }
+      responses:
+        "200":
+          description: The item with its responses.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/InboxItem" }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+
   /api/inbox/responses:
     post:
       operationId: respondInbox
@@ -1489,7 +1526,7 @@ components:
         task_id: { type: string }
         agent_session_id: { type: string }
         thread_id: { type: string }
-        kind: { type: string, enum: [question, session_error, rate_limited] }
+        kind: { type: string, enum: [question, session_error, rate_limited, client_run] }
         payload:
           type: object
           description: >
@@ -1497,6 +1534,7 @@ components:
             question, why_blocked, options (each choice's text, in order), multiple (true for pick-any), recommended (the marked choices' text), attachments.
             session_error: error.
             rate_limited: vendor, rate_limit (the vendor's rate-limit status), error.
+            client_run: why, command, paths (worktree paths in the bundle), bytes (the bundle's size).
         state: { $ref: "#/components/schemas/InboxState" }
         created_at: { type: string, format: date-time }
         resolved_by: { type: string }
@@ -1507,7 +1545,7 @@ components:
 
     InboxResponseType:
       type: string
-      enum: [option, other, dismiss]
+      enum: [option, other, dismiss, run]
 
     InboxResponse:
       type: object
@@ -1520,7 +1558,9 @@ components:
         options:
           type: array
           items: { type: string }
-        text: { type: string }
+        text: { type: string, description: "run: the command's output, at most its last 64 KiB." }
+        client: { type: string, description: "run: the host name of the Mac that ran the command." }
+        exit_code: { type: integer, description: "run: the command's exit status." }
         images:
           type: array
           items: { type: string }
@@ -1550,6 +1590,15 @@ components:
           type: array
           items: { $ref: "#/components/schemas/Attachment" }
 
+    RunReport:
+      type: object
+      required: [run_id, client, exit_code, output]
+      properties:
+        run_id: { type: string, description: "The Mac's id for this one run, used as the response's id; reporting it again records nothing new." }
+        client: { type: string }
+        exit_code: { type: integer }
+        output: { type: string }
+
     InboxRespond:
       type: object
       required: [responses]