ask: rename ask_operator → ask + optional 'to' for agent-to-agent Q&A

hive-c0re/src/questions.rs

@@ -0,0 +1,128 @@
+//! Shared dispatch helpers for the `Ask` / `Answer` flow. Both the
+//! agent socket and the manager socket call into here so the routing
+//! semantics — recipient = operator vs. peer agent, answerer
+//! authorisation, asker-notification — only live in one place.
+//!
+//! Routing rules at a glance:
+//!
+//! - `Ask { to: None | Some("operator") }` → stored with `target = NULL`;
+//!   the dashboard's `pending()` query surfaces it; operator answers
+//!   via the dashboard.
+//! - `Ask { to: Some(<agent>) }` → stored with `target = <agent>`;
+//!   a `HelperEvent::QuestionAsked` is pushed into `<agent>`'s
+//!   inbox so they can `Answer { id, answer }` on their own socket.
+//! - `Answer { id, answer }` → permission-checked in
+//!   `OperatorQuestions::answer` (only the target agent or the
+//!   operator can answer; both paths fire the same
+//!   `QuestionAnswered` event to the asker).
+
+use std::sync::Arc;
+
+use crate::coordinator::Coordinator;
+use crate::limits;
+use crate::manager_server::spawn_question_watchdog;
+
+/// Cap on how long an asker can demand an answer before the watchdog
+/// auto-resolves with `[expired]`. Six hours mirrors typical agent
+/// session lifetimes — beyond that an unanswered question is
+/// effectively a dead thread and should be re-asked, not blocked on.
+const MAX_TTL_SECONDS: u64 = 6 * 60 * 60;
+
+/// Handle either surface's `Ask` request. Returns the queued
+/// question id on success or a caller-ready error string. Caller is
+/// responsible for wrapping in the matching `*Response::Err` /
+/// `QuestionQueued` variant.
+pub fn handle_ask(
+    coord: &Arc<Coordinator>,
+    asker: &str,
+    question: &str,
+    options: &[String],
+    multi: bool,
+    ttl_seconds: Option<u64>,
+    to: Option<&str>,
+) -> Result<i64, String> {
+    limits::check_size("question", question)?;
+    // Normalise `Some("operator")` → None so the storage layer
+    // only has to think about NULL vs. non-NULL targets, not
+    // "is this string the operator?".
+    let target = match to {
+        None => None,
+        Some(t) if t == hive_sh4re::OPERATOR_RECIPIENT => None,
+        Some("") => {
+            return Err("ask: `to` cannot be empty (omit it for the operator path)".to_owned());
+        }
+        Some(t) if t == asker => {
+            return Err("ask: cannot ask yourself a question (would loop forever)".to_owned());
+        }
+        Some(t) => Some(t),
+    };
+    let ttl = ttl_seconds.map(|s| s.min(MAX_TTL_SECONDS));
+    let deadline_at = ttl.and_then(|s| {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .ok()
+            .and_then(|d| i64::try_from(d.as_secs()).ok())
+            .unwrap_or(0);
+        i64::try_from(s).ok().map(|s| now + s)
+    });
+    let id = coord
+        .questions
+        .submit(asker, question, options, multi, deadline_at, target)
+        .map_err(|e| format!("{e:#}"))?;
+    tracing::info!(%id, %asker, ?target, ?deadline_at, "question queued");
+    // Agent-targeted questions need to wake the recipient — drop a
+    // QuestionAsked event into their inbox so the answerer doesn't
+    // have to poll. Operator-targeted questions show up on the
+    // dashboard's pending pane via `pending()` instead.
+    if let Some(target_agent) = target {
+        coord.notify_agent(
+            target_agent,
+            &hive_sh4re::HelperEvent::QuestionAsked {
+                id,
+                asker: asker.to_owned(),
+                question: question.to_owned(),
+                options: options.to_vec(),
+                multi,
+            },
+        );
+    }
+    if let Some(t) = ttl {
+        spawn_question_watchdog(coord, id, t);
+    }
+    Ok(id)
+}
+
+/// Handle either surface's `Answer` request. Returns `Ok(())` on
+/// success or a caller-ready error string. Authorisation lives in
+/// `OperatorQuestions::answer` — we only have to wire the result
+/// back to the asker as a `QuestionAnswered` event.
+pub fn handle_answer(
+    coord: &Arc<Coordinator>,
+    answerer: &str,
+    id: i64,
+    answer: &str,
+) -> Result<(), String> {
+    limits::check_size("answer", answer)?;
+    let (question, asker, _target) = coord
+        .questions
+        .answer(id, answer, answerer)
+        .map_err(|e| format!("{e:#}"))?;
+    tracing::info!(%id, %answerer, %asker, "question answered");
+    coord.notify_agent(
+        &asker,
+        &hive_sh4re::HelperEvent::QuestionAnswered {
+            id,
+            question,
+            answer: answer.to_owned(),
+            answerer: answerer.to_owned(),
+        },
+    );
+    Ok(())
+}
+
+// Real coverage needs a `Coordinator` fixture (broker + sqlite +
+// in-memory questions). Skipped for now — the normalisation branches
+// in `handle_ask` are short enough to read line-by-line; once we add
+// a coord test harness, drop integration tests here for: self-target
+// rejection, operator-string passthrough, agent-to-agent QuestionAsked
+// emission, and `Answer` authorisation.