feat: epic 7964 — generic turn runner and progress ledger

crates/tinyagents-harness-tools/Cargo.toml

@@ -24,6 +24,7 @@ reqwest = { workspace = true, features = ["stream", "multipart"], optional = tru
 sha2 = { version = "0.11", optional = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
+schemars = { version = "1", features = ["derive"], optional = true }
 tinyagents-harness = { path = "../tinyagents-harness", version = "3.0.0", default-features = false }
 tinyagents-tasks = { path = "../tinyagents-tasks", version = "3.0.0", default-features = false, optional = true }
 tinyinference-llm = { path = "../../vendor/tinyinference/crates/tinyinference-llm", version = "0.5.0", optional = true }
@@ -47,6 +48,7 @@ goals = []
 skills = []
 state-block = ["goals", "todos", "dep:tinyinference-llm"]
 subagents = ["dep:tinyagents-orchestration", "dep:tinyagents-tasks", "dep:tinyinference-llm"]
+json-schema = ["dep:schemars"]
 fs = ["dep:base64", "dep:fs2", "dep:glob", "dep:libc", "dep:log", "dep:regex", "dep:walkdir", "tokio/fs", "tokio/io-util"]
 net = ["dep:futures-util", "dep:log", "dep:reqwest", "dep:sha2", "tokio/fs", "tokio/io-util"]
 exec = ["dep:rustix", "tokio/fs", "tokio/io-util", "tokio/process"]

crates/tinyagents-harness-tools/README.md

@@ -11,7 +11,8 @@ feature enables the generic job and message tools and brings in
 `tinyagents-orchestration` and its task registry dependencies. Time,
 clarification, plan-exit, per-call binding, and thread-lock support are
 available without optional features. The `state-block` feature enables the
-run-state middleware and its required `goals` and `todos` modules.
+run-state middleware and its required `goals` and `todos` modules. The
+`json-schema` feature enables schema derives on tool-owned data types.
 
 The opt-in `fs`, `net`, and `exec` features expose the standard tool families
 under `tinyagents_harness_tools::{fs,net,exec}`. The `media` feature exposes
@@ -50,6 +51,10 @@ default set.
   `AskClarificationTool`, `PlanExitTool`, `WaitTool`, `WaitLoopTool`, and the
   `per_call` binding adapter.
 
+`WaitTool` and `WaitLoopTool` provide bounded delayed callback ticks for
+orchestrator-controlled polling. They return the caller's callback message
+without owning scheduling state.
+
 Subagent registry policy stays in `tinyagents-orchestration`; this crate owns
 the reusable tool declarations. The harness owns tool registration,
 admission, schema preparation, discovery, and dispatch infrastructure.

crates/tinyagents-harness-tools/src/goals/mod_tests.rs

@@ -3,6 +3,40 @@
 use super::prompt::*;
 use super::types::*;
 
+#[cfg(feature = "json-schema")]
+fn schema_string_values<'a>(
+    root: &'a serde_json::Value,
+    mut schema: &'a serde_json::Value,
+) -> Vec<String> {
+    while let Some(reference) = schema.get("$ref").and_then(serde_json::Value::as_str) {
+        let pointer = reference.strip_prefix('#').expect("local schema reference");
+        schema = root.pointer(pointer).expect("schema reference resolves");
+    }
+
+    let mut values: Vec<String> =
+        if let Some(values) = schema.get("enum").and_then(serde_json::Value::as_array) {
+            values
+                .iter()
+                .map(|value| value.as_str().expect("string enum value").to_owned())
+                .collect()
+        } else {
+            schema
+                .get("oneOf")
+                .and_then(serde_json::Value::as_array)
+                .expect("string enum or oneOf schema")
+                .iter()
+                .map(|variant| {
+                    variant["const"]
+                        .as_str()
+                        .expect("string oneOf const")
+                        .to_owned()
+                })
+                .collect()
+        };
+    values.sort();
+    values
+}
+
 fn goal(status: ThreadGoalStatus, token_budget: Option<u64>, tokens_used: u64) -> ThreadGoal {
     ThreadGoal {
         thread_id: "t".into(),
@@ -26,6 +60,50 @@ fn status_strings_match_serialized() {
     assert_eq!(ThreadGoalStatus::Complete.as_str(), "complete");
 }
 
+#[cfg(feature = "json-schema")]
+#[test]
+fn public_goal_schema_uses_the_serialized_camel_case_record() {
+    let schema = serde_json::to_value(
+        schemars::generate::SchemaSettings::draft2020_12()
+            .for_serialize()
+            .into_generator()
+            .into_root_schema_for::<ThreadGoal>(),
+    )
+    .unwrap();
+    let properties = &schema["properties"];
+    for field in [
+        "threadId",
+        "goalId",
+        "objective",
+        "status",
+        "tokenBudget",
+        "tokensUsed",
+        "timeUsedSeconds",
+        "timeUsedSubsecNanos",
+        "createdAtMs",
+        "updatedAtMs",
+    ] {
+        assert!(properties.get(field).is_some(), "missing {field}: {schema}");
+    }
+    let status_values = schema_string_values(&schema, &properties["status"]);
+    let mut expected_status_values = vec![
+        "active".to_owned(),
+        "paused".to_owned(),
+        "budget_limited".to_owned(),
+        "complete".to_owned(),
+    ];
+    expected_status_values.sort();
+    assert_eq!(status_values, expected_status_values);
+    for (status, serialized) in [
+        (ThreadGoalStatus::Active, "active"),
+        (ThreadGoalStatus::Paused, "paused"),
+        (ThreadGoalStatus::BudgetLimited, "budget_limited"),
+        (ThreadGoalStatus::Complete, "complete"),
+    ] {
+        assert_eq!(serde_json::to_value(status).unwrap(), serialized);
+    }
+}
+
 #[test]
 fn active_and_terminal_predicates() {
     assert!(ThreadGoalStatus::Active.is_active());

crates/tinyagents-harness-tools/src/goals/types.rs

@@ -20,6 +20,7 @@ use serde::{Deserialize, Serialize};
 /// system (host control and accounting respectively), and clearing deletes the
 /// row entirely rather than being a status.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
 #[serde(rename_all = "snake_case")]
 pub enum ThreadGoalStatus {
     /// The graph may make progress and (when driven) auto-continue.
@@ -61,6 +62,7 @@ impl ThreadGoalStatus {
 
 /// A single thread-scoped goal.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
 #[serde(rename_all = "camelCase")]
 pub struct ThreadGoal {
     /// The thread this goal belongs to (one goal per thread).