@band-app/server 0.32.0 → 0.33.0

package/dist/openapi.json

@@ -2169,6 +2169,104 @@
         }
       }
     },
+    "/history.import": {
+      "post": {
+        "operationId": "history.import",
+        "tags": [
+          "history"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "imported": {
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "imported"
+                          ],
+                          "additionalProperties": false
+                        }
+                      },
+                      "required": [
+                        "data"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "result"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "entries": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": {
+                          "type": "string"
+                        },
+                        "title": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "visitCount": {
+                          "type": "number"
+                        },
+                        "lastVisitedAt": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "url",
+                        "title",
+                        "visitCount",
+                        "lastVisitedAt"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "workspaceId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "entries",
+                  "workspaceId"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      }
+    },
     "/history.clear": {
       "post": {
         "operationId": "history.clear",
@@ -3919,6 +4017,54 @@
         }
       }
     },
+    "/terminal.restartDaemon": {
+      "post": {
+        "operationId": "terminal.restartDaemon",
+        "tags": [
+          "terminal"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "killedCount": {
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "killedCount"
+                          ],
+                          "additionalProperties": false
+                        }
+                      },
+                      "required": [
+                        "data"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "result"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
     "/settings.get": {
       "get": {
         "operationId": "settings.get",
@@ -4134,6 +4280,19 @@
                       }
                     },
                     "additionalProperties": {}
+                  },
+                  "agents": {
+                    "type": "object",
+                    "properties": {
+                      "defaultMode": {
+                        "type": "string",
+                        "enum": [
+                          "gui",
+                          "tui"
+                        ]
+                      }
+                    },
+                    "additionalProperties": {}
                   }
                 },
                 "additionalProperties": {}
@@ -4855,6 +5014,13 @@
                   "codingAgentId": {
                     "type": "string"
                   },
+                  "agentMode": {
+                    "type": "string",
+                    "enum": [
+                      "gui",
+                      "tui"
+                    ]
+                  },
                   "via": {
                     "type": "string",
                     "enum": [
@@ -5873,9 +6039,9 @@
         ]
       }
     },
-    "/workspace.getDiffSummary": {
+    "/workspace.getChanges": {
       "get": {
-        "operationId": "workspace.getDiffSummary",
+        "operationId": "workspace.getChanges",
         "tags": [
           "workspace"
         ],
@@ -5891,7 +6057,7 @@
                       "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/DiffSummaryResult"
+                          "$ref": "#/components/schemas/ChangesResult"
                         }
                       },
                       "required": [
@@ -5924,13 +6090,6 @@
                     "workspaceId": {
                       "type": "string"
                     },
-                    "diffMode": {
-                      "type": "string",
-                      "enum": [
-                        "branch",
-                        "uncommitted"
-                      ]
-                    },
                     "compareBranch": {
                       "type": "string"
                     }
@@ -6009,17 +6168,32 @@
                     "filePath": {
                       "type": "string"
                     },
-                    "mergeBase": {
-                      "type": "string"
+                    "section": {
+                      "type": "string",
+                      "enum": [
+                        "branch",
+                        "conflicts",
+                        "unstaged",
+                        "staged",
+                        "untracked"
+                      ]
                     },
                     "contextLines": {
                       "type": "number"
+                    },
+                    "mergeBase": {
+                      "type": "string",
+                      "description": "Required for the `branch` section."
+                    },
+                    "oldPath": {
+                      "type": "string",
+                      "description": "The path before a rename, so git pairs the two sides."
                     }
                   },
                   "required": [
                     "workspaceId",
                     "filePath",
-                    "mergeBase"
+                    "section"
                   ],
                   "additionalProperties": false
                 }
@@ -6029,9 +6203,9 @@
         ]
       }
     },
-    "/workspace.revertFile": {
+    "/workspace.stageFiles": {
       "post": {
-        "operationId": "workspace.revertFile",
+        "operationId": "workspace.stageFiles",
         "tags": [
           "workspace"
         ],
@@ -6086,24 +6260,16 @@
                   "workspaceId": {
                     "type": "string"
                   },
-                  "filePath": {
-                    "type": "string"
-                  },
-                  "diffMode": {
-                    "type": "string",
-                    "enum": [
-                      "branch",
-                      "uncommitted"
-                    ]
-                  },
-                  "compareBranch": {
-                    "type": "string"
+                  "paths": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 },
                 "required": [
                   "workspaceId",
-                  "filePath",
-                  "diffMode"
+                  "paths"
                 ],
                 "additionalProperties": false
               }
@@ -6112,9 +6278,9 @@
         }
       }
     },
-    "/workspace.gitPull": {
+    "/workspace.unstageFiles": {
       "post": {
-        "operationId": "workspace.gitPull",
+        "operationId": "workspace.unstageFiles",
         "tags": [
           "workspace"
         ],
@@ -6168,10 +6334,17 @@
                 "properties": {
                   "workspaceId": {
                     "type": "string"
+                  },
+                  "paths": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 },
                 "required": [
-                  "workspaceId"
+                  "workspaceId",
+                  "paths"
                 ],
                 "additionalProperties": false
               }
@@ -6180,9 +6353,9 @@
         }
       }
     },
-    "/workspace.gitPush": {
+    "/workspace.discardChanges": {
       "post": {
-        "operationId": "workspace.gitPush",
+        "operationId": "workspace.discardChanges",
         "tags": [
           "workspace"
         ],
@@ -6236,10 +6409,26 @@
                 "properties": {
                   "workspaceId": {
                     "type": "string"
+                  },
+                  "section": {
+                    "type": "string",
+                    "enum": [
+                      "unstaged",
+                      "staged",
+                      "untracked"
+                    ]
+                  },
+                  "paths": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 },
                 "required": [
-                  "workspaceId"
+                  "workspaceId",
+                  "section",
+                  "paths"
                 ],
                 "additionalProperties": false
               }
@@ -6248,9 +6437,9 @@
         }
       }
     },
-    "/workspace.gitCommit": {
+    "/workspace.gitPull": {
       "post": {
-        "operationId": "workspace.gitCommit",
+        "operationId": "workspace.gitPull",
         "tags": [
           "workspace"
         ],
@@ -6302,18 +6491,11 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "message": {
-                    "type": "string"
-                  },
                   "workspaceId": {
                     "type": "string"
-                  },
-                  "body": {
-                    "type": "string"
                   }
                 },
                 "required": [
-                  "message",
                   "workspaceId"
                 ],
                 "additionalProperties": false
@@ -6323,9 +6505,9 @@
         }
       }
     },
-    "/workspace.generateCommitMessage": {
+    "/workspace.gitPush": {
       "post": {
-        "operationId": "workspace.generateCommitMessage",
+        "operationId": "workspace.gitPush",
         "tags": [
           "workspace"
         ],
@@ -6343,20 +6525,13 @@
                         "data": {
                           "type": "object",
                           "properties": {
-                            "message": {
-                              "type": "string"
-                            },
-                            "body": {
-                              "type": "string"
-                            },
-                            "agentLabel": {
-                              "type": "string"
+                            "ok": {
+                              "type": "boolean",
+                              "const": true
                             }
                           },
                           "required": [
-                            "message",
-                            "body",
-                            "agentLabel"
+                            "ok"
                           ],
                           "additionalProperties": false
                         }
@@ -6398,9 +6573,9 @@
         }
       }
     },
-    "/workspace.listFiles": {
-      "get": {
-        "operationId": "workspace.listFiles",
+    "/workspace.gitCommit": {
+      "post": {
+        "operationId": "workspace.gitCommit",
         "tags": [
           "workspace"
         ],
@@ -6416,7 +6591,17 @@
                       "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListFilesResult"
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean",
+                              "const": true
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ],
+                          "additionalProperties": false
                         }
                       },
                       "required": [
@@ -6435,18 +6620,158 @@
             "$ref": "#/components/responses/Error"
           }
         },
-        "parameters": [
-          {
-            "name": "input",
-            "in": "query",
-            "required": true,
-            "style": "deepObject",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "workspaceId": {
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "message": {
+                    "type": "string"
+                  },
+                  "workspaceId": {
+                    "type": "string"
+                  },
+                  "body": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "message",
+                  "workspaceId"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/workspace.generateCommitMessage": {
+      "post": {
+        "operationId": "workspace.generateCommitMessage",
+        "tags": [
+          "workspace"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "message": {
+                              "type": "string"
+                            },
+                            "body": {
+                              "type": "string"
+                            },
+                            "agentLabel": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "message",
+                            "body",
+                            "agentLabel"
+                          ],
+                          "additionalProperties": false
+                        }
+                      },
+                      "required": [
+                        "data"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "result"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "workspaceId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "workspaceId"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/workspace.listFiles": {
+      "get": {
+        "operationId": "workspace.listFiles",
+        "tags": [
+          "workspace"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListFilesResult"
+                        }
+                      },
+                      "required": [
+                        "data"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "result"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "parameters": [
+          {
+            "name": "input",
+            "in": "query",
+            "required": true,
+            "style": "deepObject",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "workspaceId": {
                       "type": "string"
                     },
                     "path": {
@@ -7321,81 +7646,6 @@
         ]
       }
     },
-    "/workspace.switchAgent": {
-      "post": {
-        "operationId": "workspace.switchAgent",
-        "tags": [
-          "workspace"
-        ],
-        "responses": {
-          "200": {
-            "description": "Successful response",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "result": {
-                      "type": "object",
-                      "properties": {
-                        "data": {
-                          "type": "object",
-                          "properties": {
-                            "ok": {
-                              "type": "boolean",
-                              "const": true
-                            }
-                          },
-                          "required": [
-                            "ok"
-                          ],
-                          "additionalProperties": false
-                        }
-                      },
-                      "required": [
-                        "data"
-                      ]
-                    }
-                  },
-                  "required": [
-                    "result"
-                  ]
-                }
-              }
-            }
-          },
-          "default": {
-            "$ref": "#/components/responses/Error"
-          }
-        },
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "workspaceId": {
-                    "type": "string"
-                  },
-                  "agentId": {
-                    "type": "string"
-                  },
-                  "chatId": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "workspaceId",
-                  "agentId"
-                ],
-                "additionalProperties": false
-              }
-            }
-          }
-        }
-      }
-    },
     "/cronjobs.list": {
       "get": {
         "operationId": "cronjobs.list",
@@ -8308,6 +8558,9 @@
                   },
                   "configId": {
                     "type": "string"
+                  },
+                  "workspaceId": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -8665,7 +8918,150 @@
                             }
                           },
                           "required": [
-                            "ok"
+                            "ok"
+                          ],
+                          "additionalProperties": false
+                        }
+                      },
+                      "required": [
+                        "data"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "result"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "chatId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "chatId"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/chats.resume": {
+      "post": {
+        "operationId": "chats.resume",
+        "tags": [
+          "chats"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ],
+                          "additionalProperties": false
+                        }
+                      },
+                      "required": [
+                        "data"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "result"
+                  ]
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "chatId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "chatId"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/chats.continueInTerminal": {
+      "post": {
+        "operationId": "chats.continueInTerminal",
+        "description": "Continue this chat's coding-agent session in a terminal pane.\n\nResolves the chat's underlying agent session ID (`activeSessionId`) and\nthe adapter for whichever coding agent it ran, asks the adapter for the\nvendor CLI's *resume* invocation (`claude --resume <id>`,\n`codex resume <id>`, `opencode --session <id>`), composes it into a\nshell-safe command, and spawns a fresh terminal pane running it — so the\nuser keeps working in the very session the web chat was running.\n\nMirrors the spawn+emit pair in `WorkspaceService.create`'s\n`via=terminal` branch (issue #551), and resolves the agent inline the\nsame way `setActiveSession` above does. Errors surface to the client so\nthe UI can keep the menu item disabled for agents that can't resume\n(Gemini CLI / Cursor CLI) or chats with no session yet.",
+        "tags": [
+          "chats"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "terminalId": {
+                              "type": "string"
+                            },
+                            "workspaceId": {
+                              "type": "string"
+                            },
+                            "sessionId": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "terminalId",
+                            "workspaceId",
+                            "sessionId"
                           ],
                           "additionalProperties": false
                         }
@@ -8707,11 +9103,11 @@
         }
       }
     },
-    "/chats.resume": {
-      "post": {
-        "operationId": "chats.resume",
+    "/agentSessions.list": {
+      "get": {
+        "operationId": "agentSessions.list",
         "tags": [
-          "chats"
+          "agentSessions"
         ],
         "responses": {
           "200": {
@@ -8727,12 +9123,15 @@
                         "data": {
                           "type": "object",
                           "properties": {
-                            "ok": {
-                              "type": "boolean"
+                            "agentSessions": {
+                              "type": "array",
+                              "items": {
+                                "$ref": "#/components/schemas/AgentSessionRecord"
+                              }
                             }
                           },
                           "required": [
-                            "ok"
+                            "agentSessions"
                           ],
                           "additionalProperties": false
                         }
@@ -8753,33 +9152,38 @@
             "$ref": "#/components/responses/Error"
           }
         },
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "chatId": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "chatId"
-                ],
-                "additionalProperties": false
+        "parameters": [
+          {
+            "name": "input",
+            "in": "query",
+            "required": true,
+            "style": "deepObject",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "workspaceId": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "workspaceId"
+                  ],
+                  "additionalProperties": false
+                }
               }
             }
           }
-        }
+        ]
       }
     },
-    "/chats.continueInTerminal": {
+    "/agentSessions.launch": {
       "post": {
-        "operationId": "chats.continueInTerminal",
-        "description": "Continue this chat's coding-agent session in a terminal pane.\n\nResolves the chat's underlying agent session ID (`activeSessionId`) and\nthe adapter for whichever coding agent it ran, asks the adapter for the\nvendor CLI's *resume* invocation (`claude --resume <id>`,\n`codex resume <id>`, `opencode --session <id>`), composes it into a\nshell-safe command, and spawns a fresh terminal pane running it — so the\nuser keeps working in the very session the web chat was running.\n\nMirrors the spawn+emit pair in `WorkspaceService.create`'s\n`via=terminal` branch (issue #551), and resolves the agent inline the\nsame way `setActiveSession` above does. Errors surface to the client so\nthe UI can keep the menu item disabled for agents that can't resume\n(Gemini CLI / Cursor CLI) or chats with no session yet.",
+        "operationId": "agentSessions.launch",
+        "description": "Start an agent. `mode` is the calling device's choice; without it the\nserver's `agents.defaultMode` applies. The response carries the mode\nactually used, which is `gui` when the agent has no TUI invocation.",
         "tags": [
-          "chats"
+          "agentSessions"
         ],
         "responses": {
           "200": {
@@ -8793,24 +9197,7 @@
                       "type": "object",
                       "properties": {
                         "data": {
-                          "type": "object",
-                          "properties": {
-                            "terminalId": {
-                              "type": "string"
-                            },
-                            "workspaceId": {
-                              "type": "string"
-                            },
-                            "sessionId": {
-                              "type": "string"
-                            }
-                          },
-                          "required": [
-                            "terminalId",
-                            "workspaceId",
-                            "sessionId"
-                          ],
-                          "additionalProperties": false
+                          "$ref": "#/components/schemas/result"
                         }
                       },
                       "required": [
@@ -8836,12 +9223,31 @@
               "schema": {
                 "type": "object",
                 "properties": {
+                  "workspaceId": {
+                    "type": "string"
+                  },
+                  "prompt": {
+                    "type": "string"
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "gui",
+                      "tui"
+                    ]
+                  },
                   "chatId": {
                     "type": "string"
+                  },
+                  "terminalId": {
+                    "type": "string"
+                  },
+                  "agentId": {
+                    "type": "string"
                   }
                 },
                 "required": [
-                  "chatId"
+                  "workspaceId"
                 ],
                 "additionalProperties": false
               }
@@ -11232,6 +11638,20 @@
             },
             "additionalProperties": {},
             "description": "CLI-scoped preferences (issue #551). Today only `defaultVia` is\nrecognized — the user-level fallback for `band workspaces create\n--prompt` dispatch when no `--via` flag, `BAND_DISPATCH` env var,\nor repo `.band/config.json` value is set."
+          },
+          "agents": {
+            "type": "object",
+            "properties": {
+              "defaultMode": {
+                "type": "string",
+                "enum": [
+                  "gui",
+                  "tui"
+                ]
+              }
+            },
+            "additionalProperties": {},
+            "description": "Agent preferences (issue #682). `defaultMode` is how an agent session\nstarts when the caller sends no mode: `gui` in a chat pane, `tui` as the\nagent's CLI in a terminal. Browsers keep their own per-device mode and\nalways send it, so this applies to the CLI, cronjobs and MCP. Replaces\n`cli.defaultVia`, which boot migrates once."
           }
         },
         "additionalProperties": {}
@@ -11740,38 +12160,127 @@
         ],
         "additionalProperties": false
       },
-      "DiffSummaryResult": {
+      "ChangesResult": {
         "type": "object",
         "properties": {
-          "stats": {
-            "$ref": "#/components/schemas/DiffStats"
-          },
-          "compareBranch": {
+          "headBranch": {
             "type": "string"
           },
           "defaultBranch": {
             "type": "string"
           },
-          "headBranch": {
-            "type": "string"
+          "compareBranch": {
+            "type": "string",
+            "description": "The branch the `branch` section compares against."
           },
-          "fileStatuses": {
-            "type": "object",
-            "additionalProperties": {
-              "type": "string"
+          "mergeBase": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Where HEAD forked from `compareBranch`; null unless `branchStatus` is ready."
+          },
+          "branchStatus": {
+            "type": "string",
+            "enum": [
+              "ready",
+              "invalid-base",
+              "no-merge-base",
+              "unborn-head"
+            ],
+            "description": "Why the `branch` section is empty when it isn't `ready`: the compare\nbranch doesn't resolve (`invalid-base`), it shares no history with HEAD\n(`no-merge-base`), or there are no commits yet (`unborn-head`)."
+          },
+          "conflicts": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEntry"
             }
           },
-          "mergeBase": {
-            "type": "string"
+          "unstaged": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEntry"
+            }
+          },
+          "staged": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEntry"
+            }
+          },
+          "untracked": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEntry"
+            }
+          },
+          "branch": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEntry"
+            }
           }
         },
         "required": [
-          "stats",
-          "compareBranch",
-          "defaultBranch",
           "headBranch",
-          "fileStatuses",
-          "mergeBase"
+          "defaultBranch",
+          "compareBranch",
+          "mergeBase",
+          "branchStatus",
+          "conflicts",
+          "unstaged",
+          "staged",
+          "untracked",
+          "branch"
+        ],
+        "additionalProperties": false
+      },
+      "ChangeEntry": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "oldPath": {
+            "type": "string",
+            "description": "The path before a rename or copy."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "A",
+              "M",
+              "D",
+              "R",
+              "C",
+              "U"
+            ],
+            "description": "`A`dded, `M`odified, `D`eleted, `R`enamed, `C`opied, `U`ntracked."
+          },
+          "additions": {
+            "type": "number",
+            "description": "Lines added / deleted; unset for binary files."
+          },
+          "deletions": {
+            "type": "number"
+          },
+          "conflict": {
+            "type": "string",
+            "enum": [
+              "both_modified",
+              "both_added",
+              "both_deleted",
+              "added_by_us",
+              "added_by_them",
+              "deleted_by_us",
+              "deleted_by_them"
+            ],
+            "description": "Set on `conflicts` entries only."
+          }
+        },
+        "required": [
+          "path",
+          "status"
         ],
         "additionalProperties": false
       },
@@ -12507,6 +13016,107 @@
         ],
         "additionalProperties": false
       },
+      "AgentSessionRecord": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "workspaceId": {
+            "type": "string"
+          },
+          "agentDefinitionId": {
+            "type": "string"
+          },
+          "providerSessionId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The agent's own session id (e.g. Claude's `session_id`), null until known."
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "gui",
+              "tui"
+            ],
+            "description": "Agent session types shared by the server and the dashboard (issue #682).\n\nAn agent session is one run of a coding agent. Its `mode` says how it is\ndisplayed: `gui` in a chat pane, `tui` as the agent's CLI in a terminal.\nThe mode is fixed for the life of the session."
+          },
+          "chatId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Set for `gui` sessions."
+          },
+          "terminalId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Set for `tui` sessions."
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "running",
+              "starting",
+              "ended"
+            ]
+          },
+          "createdAt": {
+            "type": "number"
+          },
+          "updatedAt": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "id",
+          "workspaceId",
+          "agentDefinitionId",
+          "providerSessionId",
+          "mode",
+          "chatId",
+          "terminalId",
+          "state",
+          "createdAt",
+          "updatedAt"
+        ],
+        "additionalProperties": false
+      },
+      "result": {
+        "type": "object",
+        "properties": {
+          "agentSession": {
+            "$ref": "#/components/schemas/AgentSessionRecord"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "gui",
+              "tui"
+            ],
+            "description": "Agent session types shared by the server and the dashboard (issue #682).\n\nAn agent session is one run of a coding agent. Its `mode` says how it is\ndisplayed: `gui` in a chat pane, `tui` as the agent's CLI in a terminal.\nThe mode is fixed for the life of the session."
+          },
+          "chatId": {
+            "type": "string"
+          },
+          "terminalId": {
+            "type": "string"
+          },
+          "notice": {
+            "type": "string",
+            "description": "Why the requested mode wasn't used, e.g. an agent without a TUI invocation."
+          }
+        },
+        "required": [
+          "agentSession",
+          "mode"
+        ],
+        "additionalProperties": false
+      },
       "BrowserRow": {
         "type": "object",
         "properties": {