feat: add goose-client crate for programmatic goose-server access

Author: wpfleger96

Cargo.lock

@@ -0,0 +1,27 @@
+[package]
+name = "goose-client"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "HTTP client for the goose agent server"
+
+[lints]
+workspace = true
+
+[dependencies]
+goose = { path = "../goose", default-features = false }
+reqwest = { workspace = true, features = ["rustls", "json", "stream", "query"] }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true }
+tokio-stream = { workspace = true }
+futures = { workspace = true }
+tracing = { workspace = true }
+bytes = { workspace = true }
+
+[dev-dependencies]
+wiremock = { workspace = true }
+tokio = { workspace = true }

crates/goose-client/Cargo.toml

@@ -0,0 +1,25 @@
+use crate::error::Result;
+use crate::types::requests::ConfirmToolActionRequest;
+use crate::GooseClient;
+use goose::permission::permission_confirmation::Permission;
+
+impl GooseClient {
+    /// Confirm or deny a pending tool action request.
+    ///
+    /// `id` is the tool request ID received in the SSE stream's `MessageEvent::Message`
+    /// content as a `ToolRequest`. `action` is typically `Permission::AllowOnce`,
+    /// `Permission::DenyOnce`, or `Permission::AlwaysAllow`.
+    pub async fn confirm_tool_action(
+        &self,
+        id: impl Into<String>,
+        action: Permission,
+        session_id: impl Into<String>,
+    ) -> Result<()> {
+        self.http
+            .post_empty(
+                "/action-required/tool-confirmation",
+                &ConfirmToolActionRequest::new(id, action, session_id),
+            )
+            .await
+    }
+}

crates/goose-client/src/api/action_required.rs

@@ -0,0 +1,131 @@
+use crate::error::Result;
+use crate::types::requests::{
+    AddExtensionRequest, RemoveExtensionRequest, RestartAgentRequest, ResumeAgentRequest,
+    StartAgentRequest, StopAgentRequest, UpdateFromSessionRequest, UpdateProviderRequest,
+    UpdateWorkingDirRequest,
+};
+use crate::types::responses::{RestartAgentResponse, ResumeAgentResponse};
+use crate::GooseClient;
+use goose::agents::ExtensionConfig;
+use goose::session::Session;
+
+impl GooseClient {
+    /// Start a new agent session and return the created `Session`.
+    pub async fn start_agent(&self, request: StartAgentRequest) -> Result<Session> {
+        self.http.post("/agent/start", &request).await
+    }
+
+    /// Resume an existing session, optionally reloading the model and extensions.
+    pub async fn resume_agent(
+        &self,
+        session_id: impl Into<String>,
+        load_model_and_extensions: bool,
+    ) -> Result<ResumeAgentResponse> {
+        self.http
+            .post(
+                "/agent/resume",
+                &ResumeAgentRequest {
+                    session_id: session_id.into(),
+                    load_model_and_extensions,
+                },
+            )
+            .await
+    }
+
+    /// Stop and remove the agent for the given session.
+    pub async fn stop_agent(&self, session_id: impl Into<String>) -> Result<()> {
+        self.http
+            .post_empty(
+                "/agent/stop",
+                &StopAgentRequest {
+                    session_id: session_id.into(),
+                },
+            )
+            .await
+    }
+
+    /// Restart the agent for the given session (reloads extensions and provider).
+    pub async fn restart_agent(
+        &self,
+        session_id: impl Into<String>,
+    ) -> Result<RestartAgentResponse> {
+        self.http
+            .post(
+                "/agent/restart",
+                &RestartAgentRequest {
+                    session_id: session_id.into(),
+                },
+            )
+            .await
+    }
+
+    /// Change the working directory for an existing session. The agent is restarted.
+    pub async fn update_working_dir(
+        &self,
+        session_id: impl Into<String>,
+        working_dir: impl Into<String>,
+    ) -> Result<()> {
+        self.http
+            .post_empty(
+                "/agent/update_working_dir",
+                &UpdateWorkingDirRequest {
+                    session_id: session_id.into(),
+                    working_dir: working_dir.into(),
+                },
+            )
+            .await
+    }
+
+    /// Apply the session's recipe (system prompt, extensions) to the running agent.
+    pub async fn update_from_session(&self, session_id: impl Into<String>) -> Result<()> {
+        self.http
+            .post_empty(
+                "/agent/update_from_session",
+                &UpdateFromSessionRequest {
+                    session_id: session_id.into(),
+                },
+            )
+            .await
+    }
+
+    /// Change the LLM provider and/or model for an existing session.
+    pub async fn update_provider(&self, request: UpdateProviderRequest) -> Result<()> {
+        self.http
+            .post_empty("/agent/update_provider", &request)
+            .await
+    }
+
+    /// Add an MCP extension to a running session.
+    pub async fn add_extension(
+        &self,
+        session_id: impl Into<String>,
+        config: ExtensionConfig,
+    ) -> Result<()> {
+        self.http
+            .post_empty(
+                "/agent/add_extension",
+                &AddExtensionRequest {
+                    session_id: session_id.into(),
+                    config,
+                },
+            )
+            .await
+    }
+
+    /// Remove an MCP extension from a running session by name.
+    pub async fn remove_extension(
+        &self,
+        session_id: impl Into<String>,
+        name: impl Into<String>,
+    ) -> Result<()> {
+        self.http
+            .post_empty(
+                "/agent/remove_extension",
+                &RemoveExtensionRequest {
+                    session_id: session_id.into(),
+                    name: name.into(),
+                },
+            )
+            .await
+    }
+}

crates/goose-client/src/api/agent.rs

@@ -0,0 +1,32 @@
+use crate::error::Result;
+use crate::streaming::SseStream;
+use crate::types::events::MessageEvent;
+use crate::types::requests::ChatRequest;
+use crate::GooseClient;
+use futures::Stream;
+use goose::conversation::message::Message;
+
+impl GooseClient {
+    /// Send a message and receive a streaming reply.
+    ///
+    /// Returns a `Stream` of `MessageEvent` items. The stream ends with a
+    /// `MessageEvent::Finish` event. `MessageEvent::Ping` heartbeats are included
+    /// and may be filtered by the caller if not needed.
+    pub async fn reply(
+        &self,
+        request: ChatRequest,
+    ) -> Result<impl Stream<Item = Result<MessageEvent>>> {
+        let resp = self.http.post_streaming("/reply", &request).await?;
+        Ok(SseStream::new(resp.bytes_stream()))
+    }
+
+    /// Convenience wrapper: send a plain text message to an existing session.
+    pub async fn send_message(
+        &self,
+        session_id: impl Into<String>,
+        text: impl Into<String>,
+    ) -> Result<impl Stream<Item = Result<MessageEvent>>> {
+        let request = ChatRequest::new(session_id, Message::user().with_text(text.into()));
+        self.reply(request).await
+    }
+}

crates/goose-client/src/api/chat.rs

@@ -0,0 +1,6 @@
+pub mod action_required;
+pub mod agent;
+pub mod chat;
+pub mod sessions;
+pub mod status;
+pub mod tools;

crates/goose-client/src/api/mod.rs

@@ -0,0 +1,78 @@
+use crate::error::Result;
+use crate::types::requests::{ForkRequest, ImportSessionRequest, UpdateSessionNameRequest};
+use crate::types::responses::{ForkResponse, SessionListResponse};
+use crate::GooseClient;
+use goose::session::Session;
+
+impl GooseClient {
+    /// List all sessions.
+    pub async fn list_sessions(&self) -> Result<SessionListResponse> {
+        self.http.get("/sessions").await
+    }
+
+    /// Get a session by ID including its full conversation history.
+    pub async fn get_session(&self, session_id: impl AsRef<str>) -> Result<Session> {
+        self.http
+            .get(&format!("/sessions/{}", session_id.as_ref()))
+            .await
+    }
+
+    /// Delete a session permanently.
+    pub async fn delete_session(&self, session_id: impl AsRef<str>) -> Result<()> {
+        self.http
+            .delete(&format!("/sessions/{}", session_id.as_ref()))
+            .await
+    }
+
+    /// Rename a session.
+    pub async fn rename_session(
+        &self,
+        session_id: impl AsRef<str>,
+        name: impl Into<String>,
+    ) -> Result<()> {
+        self.http
+            .put_empty(
+                &format!("/sessions/{}/name", session_id.as_ref()),
+                &UpdateSessionNameRequest { name: name.into() },
+            )
+            .await
+    }
+
+    /// Export a session as a JSON string.
+    pub async fn export_session(&self, session_id: impl AsRef<str>) -> Result<String> {
+        self.http
+            .get(&format!("/sessions/{}/export", session_id.as_ref()))
+            .await
+    }
+
+    /// Import a previously exported session JSON and return the created `Session`.
+    pub async fn import_session(&self, json: impl Into<String>) -> Result<Session> {
+        self.http
+            .post(
+                "/sessions/import",
+                &ImportSessionRequest { json: json.into() },
+            )
+            .await
+    }
+
+    /// Fork a session. Set `truncate` to trim history at `timestamp`,
+    /// `copy` to create a full copy instead.
+    pub async fn fork_session(
+        &self,
+        session_id: impl AsRef<str>,
+        truncate: bool,
+        copy: bool,
+        timestamp: Option<i64>,
+    ) -> Result<ForkResponse> {
+        self.http
+            .post(
+                &format!("/sessions/{}/fork", session_id.as_ref()),
+                &ForkRequest {
+                    timestamp,
+                    truncate,
+                    copy,
+                },
+            )
+            .await
+    }
+}

crates/goose-client/src/api/sessions.rs

@@ -0,0 +1,9 @@
+use crate::error::Result;
+use crate::GooseClient;
+
+impl GooseClient {
+    /// Check that goose-server is running. Returns `"ok"` on success.
+    pub async fn status(&self) -> Result<String> {
+        self.http.get("/status").await
+    }
+}

crates/goose-client/src/api/status.rs

@@ -0,0 +1,50 @@
+use crate::error::Result;
+use crate::types::requests::CallToolRequest;
+use crate::types::responses::CallToolResponse;
+use crate::GooseClient;
+use goose::agents::extension::ToolInfo;
+
+impl GooseClient {
+    /// List all tools available in a session, optionally filtered by extension name.
+    pub async fn list_tools(
+        &self,
+        session_id: impl AsRef<str>,
+        extension_name: Option<&str>,
+    ) -> Result<Vec<ToolInfo>> {
+        let sid = session_id.as_ref();
+        match extension_name {
+            Some(ext) => {
+                self.http
+                    .get_with_query(
+                        "/agent/tools",
+                        &[("session_id", sid), ("extension_name", ext)],
+                    )
+                    .await
+            }
+            None => {
+                self.http
+                    .get_with_query("/agent/tools", &[("session_id", sid)])
+                    .await
+            }
+        }
+    }
+
+    /// Directly invoke a tool by name within a session.
+    pub async fn call_tool(
+        &self,
+        session_id: impl Into<String>,
+        name: impl Into<String>,
+        arguments: serde_json::Value,
+    ) -> Result<CallToolResponse> {
+        self.http
+            .post(
+                "/agent/call_tool",
+                &CallToolRequest {
+                    session_id: session_id.into(),
+                    name: name.into(),
+                    arguments,
+                },
+            )
+            .await
+    }
+}