ctx-mgmt: ctx session management (dev mode only) (#2415)

crates/goose-server/src/openapi.rs

@@ -9,6 +9,8 @@ use goose::message::{
 };
 use goose::permission::permission_confirmation::PrincipalType;
 use goose::providers::base::{ConfigKey, ModelInfo, ProviderMetadata};
+use goose::session::info::SessionInfo;
+use goose::session::SessionMetadata;
 use mcp_core::content::{Annotations, Content, EmbeddedResource, ImageContent, TextContent};
 use mcp_core::handler::ToolResultSchema;
 use mcp_core::resource::ResourceContents;
@@ -33,7 +35,9 @@ use utoipa::OpenApi;
         super::routes::config_management::upsert_permissions,
         super::routes::agent::get_tools,
         super::routes::reply::confirm_permission,
-        super::routes::context::manage_context, // Added this path
+        super::routes::context::manage_context,
+        super::routes::session::list_sessions,
+        super::routes::session::get_session_history
     ),
     components(schemas(
         super::routes::config_management::UpsertConfigQuery,
@@ -48,6 +52,8 @@ use utoipa::OpenApi;
         super::routes::reply::PermissionConfirmationRequest,
         super::routes::context::ContextManageRequest,
         super::routes::context::ContextManageResponse,
+        super::routes::session::SessionListResponse,
+        super::routes::session::SessionHistoryResponse,
         Message,
         MessageContent,
         Content,
@@ -76,6 +82,8 @@ use utoipa::OpenApi;
         PermissionLevel,
         PrincipalType,
         ModelInfo,
+        SessionInfo,
+        SessionMetadata,
     ))
 )]
 pub struct ApiDoc;

crates/goose-server/src/routes/session.rs

@@ -11,20 +11,41 @@ use axum::{
 use goose::message::Message;
 use goose::session;
 use goose::session::info::{get_session_info, SessionInfo, SortOrder};
+use goose::session::SessionMetadata;
 use serde::Serialize;
+use utoipa::ToSchema;
 
-#[derive(Serialize)]
-struct SessionListResponse {
+#[derive(Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionListResponse {
+    /// List of available session information objects
     sessions: Vec<SessionInfo>,
 }
 
-#[derive(Serialize)]
-struct SessionHistoryResponse {
+#[derive(Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionHistoryResponse {
+    /// Unique identifier for the session
     session_id: String,
-    metadata: session::SessionMetadata,
+    /// Session metadata containing creation time and other details
+    metadata: SessionMetadata,
+    /// List of messages in the session conversation
     messages: Vec<Message>,
 }
 
+#[utoipa::path(
+    get,
+    path = "/sessions",
+    responses(
+        (status = 200, description = "List of available sessions retrieved successfully", body = SessionListResponse),
+        (status = 401, description = "Unauthorized - Invalid or missing API key"),
+        (status = 500, description = "Internal server error")
+    ),
+    security(
+        ("api_key" = [])
+    ),
+    tag = "Session Management"
+)]
 // List all available sessions
 async fn list_sessions(
     State(state): State<Arc<AppState>>,
@@ -38,6 +59,23 @@ async fn list_sessions(
     Ok(Json(SessionListResponse { sessions }))
 }
 
+#[utoipa::path(
+    get,
+    path = "/sessions/{session_id}",
+    params(
+        ("session_id" = String, Path, description = "Unique identifier for the session")
+    ),
+    responses(
+        (status = 200, description = "Session history retrieved successfully", body = SessionHistoryResponse),
+        (status = 401, description = "Unauthorized - Invalid or missing API key"),
+        (status = 404, description = "Session not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    security(
+        ("api_key" = [])
+    ),
+    tag = "Session Management"
+)]
 // Get a specific session's history
 async fn get_session_history(
     State(state): State<Arc<AppState>>,

crates/goose/src/message.rs

@@ -77,9 +77,8 @@ pub struct RedactedThinkingContent {
     pub data: String,
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
-#[derive(ToSchema)]
 pub struct FrontendToolRequest {
     pub id: String,
     #[serde(with = "tool_result_serde")]

crates/goose/src/session/info.rs

@@ -1,10 +1,10 @@
+use crate::session::{self, SessionMetadata};
 use anyhow::Result;
 use serde::Serialize;
 use std::cmp::Ordering;
+use utoipa::ToSchema;
 
-use crate::session::{self, SessionMetadata};
-
-#[derive(Clone, Serialize)]
+#[derive(Clone, Serialize, ToSchema)]
 pub struct SessionInfo {
     pub id: String,
     pub path: String,

crates/goose/src/session/storage.rs

@@ -8,6 +8,7 @@ use std::fs::{self, File};
 use std::io::{self, BufRead, Write};
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
+use utoipa::ToSchema;
 
 fn get_home_dir() -> PathBuf {
     choose_app_strategy(crate::config::APP_STRATEGY.clone())
@@ -17,9 +18,10 @@ fn get_home_dir() -> PathBuf {
 }
 
 /// Metadata for a session, stored as the first line in the session file
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, ToSchema)]
 pub struct SessionMetadata {
     /// Working directory for the session
+    #[schema(value_type = String, example = "/home/user/sessions/session1")]
     pub working_dir: PathBuf,
     /// A short description of the session, typically 3 words or less
     pub description: String,

crates/mcp-core/src/resource.rs

@@ -26,9 +26,8 @@ pub struct Resource {
     pub annotations: Option<Annotations>,
 }
 
-#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+#[derive(ToSchema, Debug, Serialize, Deserialize, Clone, PartialEq)]
 #[serde(rename_all = "camelCase", untagged)]
-#[derive(ToSchema)]
 pub enum ResourceContents {
     TextResourceContents {
         uri: String,