Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

feat(threads): threads.state_get reads the run state in one call

sanil-2316e3c96a4eb2
diff --git a/crates/openhuman-core/src/threads/README.md b/crates/openhuman-core/src/threads/README.md
index 534e233a34..378a317e06 100644
--- a/crates/openhuman-core/src/threads/README.md
+++ b/crates/openhuman-core/src/threads/README.md
@@ -195,10 +195,13 @@ through `all_threads_registered_controllers`:
| Messages | `messages_list`, `message_append`, `message_update`, `edit_message`, `regenerate` |
| Search and transcript | `search`, `transcript_get`, `token_usage` |
| Turn state | `turn_state_get`, `turn_state_list`, `turn_state_history`, `turn_state_get_turn`, `turn_state_clear` |
-| Live agent state | `goal_get`, `todos_get` |
+| Live agent state | `goal_get`, `todos_get`, `state_get` |
-`goal_get` and `todos_get` are read-only. Goals and todos are written by the
-agent (`agent::goals`, `agent::todos`, backed by `tinyagents_graph`) and their
+`goal_get`, `todos_get` and `state_get` are read-only. `state_get` returns the
+goal, the plan and the agent's own notes (facts, blockers, approach) in one
+call, with the run-state block the model sees rendered from them (TinyAgents
+`state_block::RunState`). Goals, todos and notes are written by the
+agent (`agent::goals`, `agent::todos`, backed by `tinyagents_harness_tools`) and their
live updates stream over the web channel (`thread_goal_updated`,
`thread_goal_cleared`, `thread_todos_changed`). There is no task-board or
todo-editing surface here.
diff --git a/crates/openhuman-core/src/threads/ops.rs b/crates/openhuman-core/src/threads/ops.rs
index acdbe92188..c0a42b1f72 100644
--- a/crates/openhuman-core/src/threads/ops.rs
+++ b/crates/openhuman-core/src/threads/ops.rs
@@ -24,7 +24,8 @@ pub use edit::{
edit_message, regenerate, EditMessageRequest, EditOrRegenerateResponse, RegenerateRequest,
};
pub use live_state::{
- goal_get, todos_get, ThreadGoalGetResponse, ThreadLiveStateRequest, ThreadTodosGetResponse,
+ goal_get, state_get, todos_get, ThreadGoalGetResponse, ThreadLiveStateRequest,
+ ThreadStateGetResponse, ThreadTodosGetResponse,
};
pub use purge::threads_purge;
pub use search::{thread_search, ThreadSearchHit, ThreadSearchRequest, ThreadSearchResponse};
diff --git a/crates/openhuman-core/src/threads/ops/live_state.rs b/crates/openhuman-core/src/threads/ops/live_state.rs
index ca6e3d2690..c49eaf2fa3 100644
--- a/crates/openhuman-core/src/threads/ops/live_state.rs
+++ b/crates/openhuman-core/src/threads/ops/live_state.rs
@@ -4,14 +4,15 @@
//! separately over the web channel (`thread_goal_updated`/`thread_goal_cleared`,
//! `thread_todos_changed` — see `web_chat::event_bus`); these RPCs are the
//! one-shot "what is it right now" read a client makes when it opens a thread
-//! that already had one in flight.
+//! that already had one in flight. `state_get` reads both plus the agent's
+//! notes in one call, with the run-state block they render to.
use super::support::{envelope, workspace_dir};
use crate::agent::goals::goal_to_value;
use crate::core::Outcome;
use crate::threads::ApiEnvelope;
-/// Request for [`goal_get`] / [`todos_get`]: the thread to read.
+/// Request for [`goal_get`] / [`todos_get`] / [`state_get`]: the thread to read.
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ThreadLiveStateRequest {
pub thread_id: String,
@@ -33,6 +34,15 @@ pub struct ThreadTodosGetResponse {
pub todos: Vec<tinyagents_harness_tools::todos::TodoItem>,
}
+/// Response for [`state_get`]: what the agent's run-state block is built
+/// from (goal, plan and the agent's notes) and the block a turn would start
+/// with. For debugging and inspection; the UI keeps to the goal chip.
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct ThreadStateGetResponse {
+ pub state: tinyagents_harness_tools::state_block::RunState,
+ pub block: Option<String>,
+}
+
/// `threads.goal_get` — read a thread's current goal without waiting for the
/// next `thread_goal_updated` push (e.g. hydrating the goal chip when the
/// user reopens a thread that already had a goal in flight).
@@ -72,6 +82,36 @@ pub async fn todos_get(
Ok(envelope(ThreadTodosGetResponse { todos }, None, None))
}
+/// `threads.state_get` — read a thread's saved run state in one call: the
+/// goal, the plan, the agent's notes (and its last finished task's), plus the
+/// run-state block a turn would start with. The per-run facts (failures,
+/// files written) exist only inside a running turn and are not included.
+pub async fn state_get(
+ request: ThreadLiveStateRequest,
+) -> Result<Outcome<ApiEnvelope<ThreadStateGetResponse>>, String> {
+ let dir = workspace_dir().await?;
+ let thread_id = request.thread_id.trim();
+ if thread_id.is_empty() {
+ return Err("thread_id is required".to_string());
+ }
+ let store = crate::storage::sessions::stores_or_ephemeral(&dir).kv;
+ // Each part is read on its own: one the store cannot return is left out
+ // (and logged by TinyAgents), the rest still comes back.
+ let state = tinyagents_harness_tools::state_block::RunState::load(&store, thread_id).await;
+ log::debug!(
+ "[threads] state_get thread_id={thread_id} goal={} steps={} notes={}",
+ state.goal.is_some(),
+ state.todos.len(),
+ state.notes.is_some()
+ );
+ let block = state.render();
+ Ok(envelope(
+ ThreadStateGetResponse { state, block },
+ None,
+ None,
+ ))
+}
+
#[cfg(test)]
#[path = "live_state_tests.rs"]
mod tests;
diff --git a/crates/openhuman-core/src/threads/ops/live_state_tests.rs b/crates/openhuman-core/src/threads/ops/live_state_tests.rs
index 50d7dff5cb..1d9aaa0faf 100644
--- a/crates/openhuman-core/src/threads/ops/live_state_tests.rs
+++ b/crates/openhuman-core/src/threads/ops/live_state_tests.rs
@@ -122,3 +122,67 @@ async fn todos_get_reads_back_what_the_todo_tool_wrote() {
assert_eq!(todos.len(), 1);
assert_eq!(todos[0]["content"], "write tests");
}
+
+/// `threads.state_get` reads goal, plan and the agent's notes in one call,
+/// with the run-state block they render to.
+#[tokio::test]
+async fn state_get_reads_goal_plan_and_notes_with_the_block() {
+ let _ws = WorkspaceGuard::new().await;
+ let dir = crate::config::Config::load_or_init()
+ .await
+ .unwrap()
+ .workspace_dir;
+
+ let empty = state_get(ThreadLiveStateRequest {
+ thread_id: "thread-state-live".to_string(),
+ })
+ .await
+ .unwrap();
+ let empty_json = empty.into_cli_compatible_json().unwrap();
+ assert!(empty_json["data"]["block"].is_null(), "{empty_json}");
+
+ let store = crate::storage::sessions::stores_or_ephemeral(&dir).kv;
+ tinyagents_harness_tools::goals::store::set(&store, "thread-state-live", "ship it", None)
+ .await
+ .unwrap();
+ tinyagents_harness_tools::todos::store::replace(
+ &store,
+ "thread-state-live",
+ vec![TodoItem::with_status("write tests", TodoStatus::InProgress)],
+ )
+ .await
+ .unwrap();
+ tinyagents_harness_tools::scratchpad::store::apply(
+ &store,
+ "thread-state-live",
+ &tinyagents_harness_tools::scratchpad::ScratchpadUpdate {
+ facts: vec!["the suite uses nextest".to_string()],
+ ..Default::default()
+ },
+ )
+ .await
+ .unwrap();
+
+ let filled = state_get(ThreadLiveStateRequest {
+ thread_id: "thread-state-live".to_string(),
+ })
+ .await
+ .unwrap();
+ let json = filled.into_cli_compatible_json().unwrap();
+ let state = &json["data"]["state"];
+ assert_eq!(state["goal"]["objective"], "ship it", "{json}");
+ assert_eq!(state["todos"][0]["content"], "write tests", "{json}");
+ assert_eq!(
+ state["notes"]["facts"][0], "the suite uses nextest",
+ "{json}"
+ );
+ let block = json["data"]["block"].as_str().unwrap_or_default();
+ assert!(block.contains("Goal (active): ship it"), "{block}");
+ assert!(block.contains(" - the suite uses nextest"), "{block}");
+
+ assert!(state_get(ThreadLiveStateRequest {
+ thread_id: " ".to_string(),
+ })
+ .await
+ .is_err());
+}
diff --git a/crates/openhuman-core/src/threads/schemas/handlers.rs b/crates/openhuman-core/src/threads/schemas/handlers.rs
index 5350846aa3..11dabb4f69 100644
--- a/crates/openhuman-core/src/threads/schemas/handlers.rs
+++ b/crates/openhuman-core/src/threads/schemas/handlers.rs
@@ -204,6 +204,13 @@ pub(super) fn handle_todos_get(_ctx: DispatchCtx, params: Map<String, Value>) ->
})
}
+pub(super) fn handle_state_get(_ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ Box::pin(async move {
+ let p = parse::<ops::ThreadLiveStateRequest>(params)?;
+ to_json(ops::state_get(p).await?)
+ })
+}
+
pub(super) fn handle_search(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
Box::pin(async move {
let p = parse::<ops::ThreadSearchRequest>(params)?;
diff --git a/crates/openhuman-core/src/threads/schemas/registry.rs b/crates/openhuman-core/src/threads/schemas/registry.rs
index ac62edb74c..a333ada08b 100644
--- a/crates/openhuman-core/src/threads/schemas/registry.rs
+++ b/crates/openhuman-core/src/threads/schemas/registry.rs
@@ -7,10 +7,10 @@ use crate::core::ControllerSchema;
use super::handlers::{
handle_create_new, handle_delete, handle_edit_message, handle_generate_title, handle_goal_get,
handle_list, handle_message_append, handle_message_update, handle_messages_list, handle_purge,
- handle_regenerate, handle_search, handle_todos_get, handle_token_usage, handle_transcript_get,
- handle_turn_state_clear, handle_turn_state_get, handle_turn_state_get_turn,
- handle_turn_state_history, handle_turn_state_list, handle_update_labels, handle_update_title,
- handle_update_working_dir, handle_upsert,
+ handle_regenerate, handle_search, handle_state_get, handle_todos_get, handle_token_usage,
+ handle_transcript_get, handle_turn_state_clear, handle_turn_state_get,
+ handle_turn_state_get_turn, handle_turn_state_history, handle_turn_state_list,
+ handle_update_labels, handle_update_title, handle_update_working_dir, handle_upsert,
};
use super::schema_defs::schemas;
@@ -37,6 +37,7 @@ pub fn all_controller_schemas() -> Vec<ControllerSchema> {
schemas("transcript_get"),
schemas("goal_get"),
schemas("todos_get"),
+ schemas("state_get"),
schemas("edit_message"),
schemas("regenerate"),
schemas("search"),
@@ -129,6 +130,10 @@ pub fn all_registered_controllers() -> Vec<RegisteredController> {
schema: schemas("todos_get"),
handler: handle_todos_get,
},
+ RegisteredController {
+ schema: schemas("state_get"),
+ handler: handle_state_get,
+ },
RegisteredController {
schema: schemas("edit_message"),
handler: handle_edit_message,
diff --git a/crates/openhuman-core/src/threads/schemas/schema_defs.rs b/crates/openhuman-core/src/threads/schemas/schema_defs.rs
index 99c3b9d34c..2ba2f526c0 100644
--- a/crates/openhuman-core/src/threads/schemas/schema_defs.rs
+++ b/crates/openhuman-core/src/threads/schemas/schema_defs.rs
@@ -464,6 +464,24 @@ pub(crate) fn schemas(function: &str) -> ControllerSchema {
required: true,
}],
},
+ "state_get" => ControllerSchema {
+ namespace: "threads",
+ function: "state_get",
+ description:
+ "Read a thread's saved run state (goal, plan, agent notes) and the run-state block it renders to.",
+ inputs: vec![FieldSchema {
+ name: "thread_id",
+ ty: TypeSchema::String,
+ comment: "Thread identifier.",
+ required: true,
+ }],
+ outputs: vec![FieldSchema {
+ name: "result",
+ ty: TypeSchema::Json,
+ comment: "Envelope wrapping { state, block } (block is null when nothing is saved).",
+ required: true,
+ }],
+ },
"edit_message" => ControllerSchema {
namespace: "threads",
function: "edit_message",
diff --git a/crates/openhuman-core/src/threads/schemas_tests.rs b/crates/openhuman-core/src/threads/schemas_tests.rs
index 9df33cd6e4..3d3c197d1c 100644
--- a/crates/openhuman-core/src/threads/schemas_tests.rs
+++ b/crates/openhuman-core/src/threads/schemas_tests.rs
@@ -23,6 +23,7 @@ const ALL_FUNCTIONS: &[&str] = &[
"transcript_get",
"goal_get",
"todos_get",
+ "state_get",
"edit_message",
"regenerate",
"search",