diff --git a/README.md b/README.md index 47eac4b6..9640d0f9 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,3 @@ insomnia(i6a)は不休のエージェントループを回すためのエージェントプラットフォーム。 ワークフローを統括し、四六時中電力を消費し、イテレーションします。 - -## Crates - -| クレート | 概要 | -|---|---| -| `insomnia` | トップレベルアプリケーション（未実装） | -| `llm-worker` | 自律的なLLMシステムを構築するためのライブラリ | -| `llm-worker-macros` | `llm-worker`用の手続きマクロ (`#[tool_registry]`, `#[tool]`) | - -## ドキュメント - -- [要件](crates/llm-worker/docs/requirements.md) — llm-workerに求める性能 (R1-R4) -- [アーキテクチャ](crates/llm-worker/docs/architecture.md) — 3層構成とモジュール配置 diff --git a/TODO.md b/TODO.md index 1a4e5c2f..1ae742d4 100644 --- a/TODO.md +++ b/TODO.md @@ -6,6 +6,7 @@ - [ ] Protocol の設計 → [tickets/protocol-design.md](tickets/protocol-design.md) - [ ] パーミッション: パターンベースのツール実行制御 → [tickets/permission-extension-point.md](tickets/permission-extension-point.md) - [ ] ネイティブ GUI クライアント MVP → [tickets/native-gui-mvp.md](tickets/native-gui-mvp.md) +- [ ] Pod Factory: カスケード設定とプロンプト資産 → [tickets/pod-factory.md](tickets/pod-factory.md) - [ ] TUI 拡充 - [ ] 通知チャネル (Warn/Error 可視化) → [tickets/tui-notification-channel.md](tickets/tui-notification-channel.md) - [ ] Pod の明示的 shutdown → [tickets/tui-pod-shutdown.md](tickets/tui-pod-shutdown.md) diff --git a/crates/llm-worker/src/worker.rs b/crates/llm-worker/src/worker.rs index 4ab4b8e1..05913760 100644 --- a/crates/llm-worker/src/worker.rs +++ b/crates/llm-worker/src/worker.rs @@ -154,6 +154,11 @@ pub struct Worker { turn_start_cbs: Vec>, /// Turn-end callbacks turn_end_cbs: Vec>, + /// Non-fatal warning callbacks. Invoked when the Worker wants to + /// surface an advisory message to the upper layer (e.g. Pod) so it + /// can be forwarded to the user — distinct from `tracing::warn!`, + /// which is for developer-facing logs. + warning_cbs: Vec>, /// Request configuration (max_tokens, temperature, etc.) request_config: RequestConfig, /// Whether the previous run was interrupted @@ -274,6 +279,23 @@ impl Worker { self.turn_start_cbs.push(Box::new(callback)); } + /// Register a non-fatal warning callback. + /// + /// The callback is invoked with a short human-readable message + /// whenever the Worker encounters a condition that should be + /// surfaced to a human (e.g. tool output byte-cap truncation). + /// This channel is separate from `tracing::warn!`, which remains + /// in place for developer logs. + pub fn on_warning(&mut self, callback: impl Fn(&str) + Send + Sync + 'static) { + self.warning_cbs.push(Box::new(callback)); + } + + fn emit_warning(&self, message: &str) { + for cb in &self.warning_cbs { + cb(message); + } + } + /// Register a turn-end callback (receives 0-based turn number). pub fn on_turn_end(&mut self, callback: impl Fn(usize) + Send + Sync + 'static) { self.turn_end_cbs.push(Box::new(callback)); @@ -696,6 +718,13 @@ impl Worker { limit_bytes = limit, "Tool output exceeded byte limit and was truncated" ); + self.emit_warning(&format!( + "tool `{}` output truncated from {} to {} bytes (limit {})", + tool_call.name, + before, + content.len(), + limit + )); } } } @@ -962,6 +991,7 @@ impl Worker { max_turns: None, turn_start_cbs: Vec::new(), turn_end_cbs: Vec::new(), + warning_cbs: Vec::new(), request_config: RequestConfig::default(), last_run_interrupted: false, cancel_tx, @@ -1214,6 +1244,7 @@ impl Worker { max_turns: self.max_turns, turn_start_cbs: self.turn_start_cbs, turn_end_cbs: self.turn_end_cbs, + warning_cbs: self.warning_cbs, request_config: self.request_config, last_run_interrupted: self.last_run_interrupted, @@ -1286,6 +1317,7 @@ impl Worker { max_turns: self.max_turns, turn_start_cbs: self.turn_start_cbs, turn_end_cbs: self.turn_end_cbs, + warning_cbs: self.warning_cbs, request_config: self.request_config, last_run_interrupted: self.last_run_interrupted, diff --git a/crates/pod/src/agents_md.rs b/crates/pod/src/agents_md.rs index 182c809e..a89016fd 100644 --- a/crates/pod/src/agents_md.rs +++ b/crates/pod/src/agents_md.rs @@ -18,21 +18,43 @@ pub(crate) const AGENTS_MD_LIMIT: usize = 64 * 1024; const TRUNCATION_NOTICE: &str = "\n\n[truncated: AGENTS.md exceeded 64KB limit]"; -/// Read `AGENTS.md` from `cwd` if present. Returns `None` for "absent or -/// unreadable"; all non-fatal problems are logged via `tracing::warn!`. +/// Outcome of an `AGENTS.md` ingestion attempt. /// -/// - Absent: `None`, no warn. -/// - Over limit: first 64KB (UTF-8 char boundary) + truncation notice, warn. -/// - Non-UTF-8 or I/O error: `None`, warn. -pub(crate) fn read_agents_md(cwd: &Path) -> Option { +/// `body` carries the text that should be handed to the template +/// engine (if any); `warnings` are short human-readable messages that +/// Pod forwards to the user-facing notification channel. The caller +/// also gets `tracing::warn!` lines for the developer log. +pub(crate) struct AgentsMdResult { + pub body: Option, + pub warnings: Vec, +} + +/// Read `AGENTS.md` from `cwd` if present. All non-fatal problems are +/// both logged via `tracing::warn!` (developer-facing) and surfaced +/// via `AgentsMdResult::warnings` (user-facing). +/// +/// - Absent: `body = None`, no warning. +/// - Over limit: first 64KB (UTF-8 char boundary) + truncation notice, warning. +/// - Non-UTF-8 or I/O error: `body = None`, warning. +pub(crate) fn read_agents_md(cwd: &Path) -> AgentsMdResult { let path = cwd.join("AGENTS.md"); + let mut warnings = Vec::new(); let file = match File::open(&path) { Ok(f) => f, - Err(e) if e.kind() == ErrorKind::NotFound => return None, + Err(e) if e.kind() == ErrorKind::NotFound => { + return AgentsMdResult { + body: None, + warnings, + }; + } Err(e) => { warn!(path = %path.display(), error = %e, "failed to open AGENTS.md"); - return None; + warnings.push(format!("failed to open AGENTS.md ({}): {}", path.display(), e)); + return AgentsMdResult { + body: None, + warnings, + }; } }; @@ -42,7 +64,11 @@ pub(crate) fn read_agents_md(cwd: &Path) -> Option { let read_limit = (AGENTS_MD_LIMIT as u64) + 1; if let Err(e) = file.take(read_limit).read_to_end(&mut buf) { warn!(path = %path.display(), error = %e, "failed to read AGENTS.md"); - return None; + warnings.push(format!("failed to read AGENTS.md ({}): {}", path.display(), e)); + return AgentsMdResult { + body: None, + warnings, + }; } let truncated = buf.len() > AGENTS_MD_LIMIT; @@ -69,7 +95,15 @@ pub(crate) fn read_agents_md(cwd: &Path) -> Option { } Err(e) => { warn!(path = %path.display(), error = %e, "AGENTS.md is not valid UTF-8"); - return None; + warnings.push(format!( + "AGENTS.md ({}) is not valid UTF-8: {}", + path.display(), + e + )); + return AgentsMdResult { + body: None, + warnings, + }; } }; @@ -80,10 +114,18 @@ pub(crate) fn read_agents_md(cwd: &Path) -> Option { limit = AGENTS_MD_LIMIT, "AGENTS.md exceeded size limit; truncating" ); + warnings.push(format!( + "AGENTS.md ({}) exceeded {} bytes; the tail was truncated", + path.display(), + AGENTS_MD_LIMIT + )); text.push_str(TRUNCATION_NOTICE); } - Some(text) + AgentsMdResult { + body: Some(text), + warnings, + } } #[cfg(test)] @@ -95,17 +137,16 @@ mod tests { #[test] fn absent_file_returns_none() { let dir = TempDir::new().unwrap(); - assert!(read_agents_md(dir.path()).is_none()); + assert!(read_agents_md(dir.path()).body.is_none()); } #[test] fn reads_small_file_verbatim() { let dir = TempDir::new().unwrap(); fs::write(dir.path().join("AGENTS.md"), "# hello\nworld").unwrap(); - assert_eq!( - read_agents_md(dir.path()).as_deref(), - Some("# hello\nworld"), - ); + let result = read_agents_md(dir.path()); + assert_eq!(result.body.as_deref(), Some("# hello\nworld")); + assert!(result.warnings.is_empty()); } #[test] @@ -114,11 +155,13 @@ mod tests { let body = "a".repeat(AGENTS_MD_LIMIT + 1024); fs::write(dir.path().join("AGENTS.md"), &body).unwrap(); - let got = read_agents_md(dir.path()).expect("some"); + let result = read_agents_md(dir.path()); + let got = result.body.expect("some"); assert!(got.ends_with(TRUNCATION_NOTICE)); let prefix = got.strip_suffix(TRUNCATION_NOTICE).unwrap(); assert_eq!(prefix.len(), AGENTS_MD_LIMIT); assert!(prefix.chars().all(|c| c == 'a')); + assert_eq!(result.warnings.len(), 1); } #[test] @@ -127,9 +170,11 @@ mod tests { let body = "a".repeat(AGENTS_MD_LIMIT); fs::write(dir.path().join("AGENTS.md"), &body).unwrap(); - let got = read_agents_md(dir.path()).expect("some"); + let result = read_agents_md(dir.path()); + let got = result.body.expect("some"); assert_eq!(got.len(), AGENTS_MD_LIMIT); assert!(!got.contains("truncated")); + assert!(result.warnings.is_empty()); } #[test] @@ -142,12 +187,23 @@ mod tests { body.push_str(&"b".repeat(128)); fs::write(dir.path().join("AGENTS.md"), &body).unwrap(); - let got = read_agents_md(dir.path()).expect("some"); + let result = read_agents_md(dir.path()); + let got = result.body.expect("some"); assert!(got.ends_with(TRUNCATION_NOTICE)); let prefix = got.strip_suffix(TRUNCATION_NOTICE).unwrap(); // The partial 'あ' must have been dropped, leaving only the ASCII prefix. assert_eq!(prefix.len(), AGENTS_MD_LIMIT - 1); assert!(prefix.chars().all(|c| c == 'a')); + assert_eq!(result.warnings.len(), 1); + } + + #[test] + fn non_utf8_surfaces_warning() { + let dir = TempDir::new().unwrap(); + fs::write(dir.path().join("AGENTS.md"), [0xff, 0xfe, 0xfd]).unwrap(); + let result = read_agents_md(dir.path()); + assert!(result.body.is_none()); + assert_eq!(result.warnings.len(), 1); } #[test] @@ -159,7 +215,7 @@ mod tests { let dir = TempDir::new().unwrap(); let body = vec![0xffu8; AGENTS_MD_LIMIT + 1024]; fs::write(dir.path().join("AGENTS.md"), body).unwrap(); - assert!(read_agents_md(dir.path()).is_none()); + assert!(read_agents_md(dir.path()).body.is_none()); } #[test] @@ -167,6 +223,6 @@ mod tests { let dir = TempDir::new().unwrap(); // Invalid UTF-8 start byte. fs::write(dir.path().join("AGENTS.md"), [0xff, 0xfe, 0xfd]).unwrap(); - assert!(read_agents_md(dir.path()).is_none()); + assert!(read_agents_md(dir.path()).body.is_none()); } } diff --git a/crates/pod/src/controller.rs b/crates/pod/src/controller.rs index dc4885b8..eb0bab39 100644 --- a/crates/pod/src/controller.rs +++ b/crates/pod/src/controller.rs @@ -6,11 +6,12 @@ use llm_worker::llm_client::client::LlmClient; use session_store::Store; use tokio::sync::{broadcast, mpsc}; +use crate::notifier::Notifier; use crate::pod::{Pod, PodError, PodRunResult}; use crate::runtime_dir::RuntimeDir; use crate::shared_state::{PodSharedState, PodStatus}; use crate::socket_server::SocketServer; -use protocol::{ErrorCode, Event, Method, RunResult, TurnResult}; +use protocol::{ErrorCode, Event, Method, NotificationLevel, NotificationSource, RunResult, TurnResult}; // --------------------------------------------------------------------------- // PodHandle — client-facing, Clone-able @@ -22,6 +23,7 @@ pub struct PodHandle { event_tx: broadcast::Sender, pub shared_state: Arc, pub runtime_dir: Arc, + pub notifier: Notifier, } impl PodHandle { @@ -37,6 +39,11 @@ impl PodHandle { pub fn send_event(&self, event: Event) -> Result> { self.event_tx.send(event) } + + /// Emit a user-facing notification. Thin wrapper over `Notifier::notify`. + pub fn notify(&self, level: NotificationLevel, source: NotificationSource, message: String) { + self.notifier.notify(level, source, message); + } } // --------------------------------------------------------------------------- @@ -56,6 +63,7 @@ impl PodController { { let (method_tx, mut method_rx) = mpsc::channel::(32); let (event_tx, _) = broadcast::channel::(256); + let notifier = Notifier::new(event_tx.clone()); let manifest_toml = toml::to_string_pretty(pod.manifest()).unwrap_or_default(); let greeting = build_greeting(&pod); @@ -78,8 +86,14 @@ impl PodController { event_tx: event_tx.clone(), shared_state: shared_state.clone(), runtime_dir: runtime_dir.clone(), + notifier: notifier.clone(), }; + // Hand the notifier to the Pod so internal operations (compaction, + // AGENTS.md ingestion during the first turn) can emit user-facing + // notifications on the same channel. + pod.attach_notifier(notifier.clone()); + // Start socket server (lives as a background task, cleaned up on drop via RuntimeDir) let _socket_server = SocketServer::start(&handle).await?; // Keep the server alive by moving it into the controller task @@ -163,6 +177,15 @@ impl PodController { }); }); + let notifier_for_worker = notifier.clone(); + worker.on_warning(move |message| { + notifier_for_worker.notify( + NotificationLevel::Warn, + NotificationSource::Worker, + message.to_owned(), + ); + }); + // Register the builtin file-manipulation tools (Read / Write / // Edit / Glob / Grep). `ScopedFs` carries the pod-lifetime // scope/pwd; `Tracker` is session-scoped — a fresh instance per @@ -215,6 +238,11 @@ impl PodController { if new_status == PodStatus::Idle { if let Err(e) = pod.try_post_run_compact().await { tracing::warn!(error = %e, "Post-run compaction error"); + notifier.notify( + NotificationLevel::Warn, + NotificationSource::Compactor, + format!("post-run compaction error: {e}"), + ); } } @@ -249,6 +277,11 @@ impl PodController { if new_status == PodStatus::Idle { if let Err(e) = pod.try_post_run_compact().await { tracing::warn!(error = %e, "Post-run compaction error"); + notifier.notify( + NotificationLevel::Warn, + NotificationSource::Compactor, + format!("post-run compaction error: {e}"), + ); } } diff --git a/crates/pod/src/lib.rs b/crates/pod/src/lib.rs index 6f2c5606..2d9de2d1 100644 --- a/crates/pod/src/lib.rs +++ b/crates/pod/src/lib.rs @@ -1,5 +1,6 @@ pub mod controller; pub mod hook; +pub mod notifier; pub mod runtime_dir; pub mod shared_state; pub mod socket_server; @@ -17,6 +18,7 @@ mod usage_tracker; pub use token_counter::{EstimateSource, SplitPoint, TokenEstimate}; pub use controller::{PodController, PodHandle}; +pub use notifier::Notifier; pub use hook::{Hook, HookEventKind, HookRegistryBuilder}; pub use manifest::{PodManifest, ProviderConfig, ProviderKind, Scope}; pub use pod::{Pod, PodError, PodRunResult, apply_worker_manifest}; diff --git a/crates/pod/src/notifier.rs b/crates/pod/src/notifier.rs new file mode 100644 index 00000000..40d215d0 --- /dev/null +++ b/crates/pod/src/notifier.rs @@ -0,0 +1,191 @@ +//! User-facing notification channel for Pod → client. +//! +//! Separate from `tracing` (which is for developer logs). Notifications +//! are short human-readable messages the Pod layer wants a client to +//! see — for example "compaction failed", "tool output truncated". +//! +//! Each notification is broadcast on the shared `Event` channel and +//! also appended to an in-memory buffer so that clients connecting +//! after the fact still see everything emitted during the session. + +use std::collections::VecDeque; +use std::sync::{Arc, Mutex}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use tokio::sync::broadcast; + +use protocol::{Event, Notification, NotificationLevel, NotificationSource}; + +/// Upper bound on buffered notifications. When exceeded, the oldest +/// entries are discarded so a long-running session cannot leak +/// memory through a pathological loop of recurring notifications +/// (e.g. compaction failing every turn). +const MAX_BUFFERED_NOTIFICATIONS: usize = 512; + +#[derive(Clone)] +pub struct Notifier { + inner: Arc, +} + +struct Inner { + event_tx: broadcast::Sender, + buffer: Mutex>, +} + +impl Notifier { + pub fn new(event_tx: broadcast::Sender) -> Self { + Self { + inner: Arc::new(Inner { + event_tx, + buffer: Mutex::new(VecDeque::with_capacity(MAX_BUFFERED_NOTIFICATIONS)), + }), + } + } + + /// Record and broadcast a notification. + /// + /// The broadcast may have no subscribers (e.g. during Pod + /// construction before any client has connected); the buffer + /// guarantees the message is still delivered once a client + /// attaches. + /// + /// The buffer mutex is held across `broadcast::send` to make + /// `subscribe_with_snapshot` race-free — a client that snapshots + /// the buffer while holding the same lock sees every notification + /// exactly once: older ones from the snapshot, newer ones from + /// the freshly-subscribed receiver. + pub fn notify(&self, level: NotificationLevel, source: NotificationSource, message: String) { + let notification = Notification { + level, + source, + message, + timestamp_ms: now_ms(), + }; + if let Ok(mut buf) = self.inner.buffer.lock() { + if buf.len() >= MAX_BUFFERED_NOTIFICATIONS { + buf.pop_front(); + } + buf.push_back(notification.clone()); + let _ = self + .inner + .event_tx + .send(Event::Notification(notification)); + } + } + + /// Subscribe and atomically snapshot the current buffer. + /// + /// The returned snapshot contains notifications emitted before + /// this call; the receiver will deliver notifications emitted + /// after. A notification cannot appear in both. + pub fn subscribe_with_snapshot(&self) -> (Vec, broadcast::Receiver) { + let buf = self + .inner + .buffer + .lock() + .expect("notifier buffer mutex poisoned"); + let rx = self.inner.event_tx.subscribe(); + let snapshot: Vec = buf.iter().cloned().collect(); + (snapshot, rx) + } +} + +fn now_ms() -> i64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_millis() as i64) + .unwrap_or(0) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn notify_broadcasts_to_existing_subscriber() { + let (tx, _keep) = broadcast::channel::(8); + let notifier = Notifier::new(tx); + let (_snapshot, mut rx) = notifier.subscribe_with_snapshot(); + + notifier.notify( + NotificationLevel::Warn, + NotificationSource::Compactor, + "test message".into(), + ); + + match rx.try_recv() { + Ok(Event::Notification(n)) => assert_eq!(n.message, "test message"), + other => panic!("unexpected event: {other:?}"), + } + } + + #[test] + fn late_subscriber_sees_earlier_notifications_via_snapshot() { + let (tx, _keep) = broadcast::channel::(8); + let notifier = Notifier::new(tx); + + notifier.notify( + NotificationLevel::Error, + NotificationSource::Pod, + "first".into(), + ); + notifier.notify( + NotificationLevel::Warn, + NotificationSource::AgentsMd, + "second".into(), + ); + + let (snapshot, mut rx) = notifier.subscribe_with_snapshot(); + assert_eq!(snapshot.len(), 2); + assert_eq!(snapshot[0].message, "first"); + assert_eq!(snapshot[1].message, "second"); + assert!(rx.try_recv().is_err()); // nothing pending on the receiver + } + + #[test] + fn buffer_discards_oldest_past_cap() { + let (tx, _keep) = broadcast::channel::(1024); + let notifier = Notifier::new(tx); + + for i in 0..(MAX_BUFFERED_NOTIFICATIONS + 50) { + notifier.notify( + NotificationLevel::Warn, + NotificationSource::Worker, + format!("msg-{i}"), + ); + } + + let (snapshot, _rx) = notifier.subscribe_with_snapshot(); + assert_eq!(snapshot.len(), MAX_BUFFERED_NOTIFICATIONS); + // First 50 were evicted; the oldest remaining is msg-50. + assert_eq!(snapshot.first().unwrap().message, "msg-50"); + let last = format!("msg-{}", MAX_BUFFERED_NOTIFICATIONS + 49); + assert_eq!(snapshot.last().unwrap().message, last); + } + + #[test] + fn subscribe_snapshot_and_live_do_not_overlap() { + let (tx, _keep) = broadcast::channel::(8); + let notifier = Notifier::new(tx); + + notifier.notify( + NotificationLevel::Warn, + NotificationSource::Worker, + "historic".into(), + ); + let (snapshot, mut rx) = notifier.subscribe_with_snapshot(); + notifier.notify( + NotificationLevel::Error, + NotificationSource::Worker, + "live".into(), + ); + + assert_eq!(snapshot.len(), 1); + assert_eq!(snapshot[0].message, "historic"); + match rx.try_recv() { + Ok(Event::Notification(n)) => assert_eq!(n.message, "live"), + other => panic!("unexpected: {other:?}"), + } + assert!(rx.try_recv().is_err()); + } +} diff --git a/crates/pod/src/pod.rs b/crates/pod/src/pod.rs index 037d96aa..23d93b29 100644 --- a/crates/pod/src/pod.rs +++ b/crates/pod/src/pod.rs @@ -21,8 +21,10 @@ use crate::hook::{ PreToolCall, }; use crate::hook_interceptor::HookInterceptor; +use crate::notifier::Notifier; use crate::system_prompt::{SystemPromptContext, SystemPromptError, SystemPromptTemplate}; use crate::usage_tracker::UsageTracker; +use protocol::{NotificationLevel, NotificationSource}; use async_trait::async_trait; use llm_worker::interceptor::PreRequestAction; @@ -97,6 +99,9 @@ pub struct Pod { /// `Some` until `ensure_system_prompt_materialized` renders it once, /// then `None` forever — including after compaction. system_prompt_template: Option, + /// User-facing notification sink attached by the Controller at + /// spawn time. `None` in tests / direct `Pod::new` usage. + notifier: Option, } impl Pod { @@ -137,6 +142,7 @@ impl Pod { usage_history: Arc::new(Mutex::new(Vec::::new())), tracker: None, system_prompt_template: None, + notifier: None, }; pod.apply_prune_from_manifest(); Ok(pod) @@ -185,6 +191,7 @@ impl Pod { usage_history: Arc::new(Mutex::new(state.usage_history)), tracker: None, system_prompt_template: None, + notifier: None, }; pod.apply_prune_from_manifest(); Ok(pod) @@ -275,6 +282,21 @@ impl Pod { self.tracker.as_ref() } + /// Attach a user-facing notification sink. + /// + /// Called by the Controller immediately after spawning so that + /// Pod-internal operations (compaction failures, AGENTS.md + /// ingestion warnings) can surface messages to connected clients. + pub fn attach_notifier(&mut self, notifier: Notifier) { + self.notifier = Some(notifier); + } + + fn notify(&self, level: NotificationLevel, source: NotificationSource, message: String) { + if let Some(n) = self.notifier.as_ref() { + n.notify(level, source, message); + } + } + // --- Hook registration --- fn assert_hooks_open(&self) { @@ -392,6 +414,7 @@ impl Pod { let Some(template) = self.system_prompt_template.take() else { return Ok(()); }; + let notifier = self.notifier.clone(); let worker = self.worker.as_mut().expect("worker present"); // Materialise any pending tool factories so the template sees the // full list of tool names. Redundant with the flush inside @@ -404,7 +427,17 @@ impl Pod { .map(|d| d.name) .collect(); let mut files = std::collections::BTreeMap::new(); - if let Some(body) = read_agents_md(&self.pwd) { + let agents_md = read_agents_md(&self.pwd); + for warning in agents_md.warnings { + if let Some(n) = notifier.as_ref() { + n.notify( + NotificationLevel::Warn, + NotificationSource::AgentsMd, + warning, + ); + } + } + if let Some(body) = agents_md.body { files.insert("agents_md".to_string(), body); } let ctx = SystemPromptContext { @@ -553,6 +586,11 @@ impl Pod { } Err(e) => { warn!(error = %e, "Compaction failed during run"); + self.notify( + NotificationLevel::Error, + NotificationSource::Compactor, + format!("mid-run compaction failed: {e}"), + ); if let Some(ref state) = self.compact_state { state.record_compact_failure(); } @@ -583,6 +621,11 @@ impl Pod { } Err(e) => { warn!(error = %e, "Proactive post-run compaction failed"); + self.notify( + NotificationLevel::Warn, + NotificationSource::Compactor, + format!("post-run compaction failed: {e}"), + ); state.record_compact_failure(); Ok(()) } @@ -830,6 +873,7 @@ impl Pod, St> { usage_history: Arc::new(Mutex::new(Vec::new())), tracker: None, system_prompt_template, + notifier: None, }; pod.apply_prune_from_manifest(); Ok(pod) diff --git a/crates/pod/src/socket_server.rs b/crates/pod/src/socket_server.rs index 92f84100..d81cab66 100644 --- a/crates/pod/src/socket_server.rs +++ b/crates/pod/src/socket_server.rs @@ -61,7 +61,21 @@ async fn handle_connection(stream: tokio::net::UnixStream, handle: PodHandle) { let (reader, writer) = stream.into_split(); let mut reader = JsonLineReader::new(reader); let mut writer = JsonLineWriter::new(writer); - let mut rx = handle.subscribe(); + + // Atomically subscribe and snapshot buffered notifications so that + // warnings emitted before this client connected are replayed + // exactly once — they appear in the snapshot, and any notification + // arriving afterwards reaches us through `rx`. + let (notification_snapshot, mut rx) = handle.notifier.subscribe_with_snapshot(); + for notification in notification_snapshot { + if writer + .write(&Event::Notification(notification)) + .await + .is_err() + { + return; + } + } loop { tokio::select! { diff --git a/crates/protocol/src/lib.rs b/crates/protocol/src/lib.rs index dcdd4fa9..f94699ce 100644 --- a/crates/protocol/src/lib.rs +++ b/crates/protocol/src/lib.rs @@ -68,6 +68,38 @@ pub enum Event { items: Vec, greeting: Greeting, }, + Notification(Notification), +} + +/// User-facing notification emitted from the Pod layer. +/// +/// This is a separate channel from `tracing` (developer logs): entries +/// here are assembled explicitly by the Pod when a condition should be +/// surfaced to the person driving the client. Keep messages short and +/// human-readable. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Notification { + pub level: NotificationLevel, + pub source: NotificationSource, + pub message: String, + /// Milliseconds since the Unix epoch. + pub timestamp_ms: i64, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum NotificationLevel { + Warn, + Error, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum NotificationSource { + Pod, + Worker, + Compactor, + AgentsMd, } /// Pod self-description rendered by the TUI when a session starts empty. @@ -187,6 +219,23 @@ mod tests { assert_eq!(parsed["data"]["greeting"]["tools"][0], "Read"); } + #[test] + fn event_notification_format() { + let event = Event::Notification(Notification { + level: NotificationLevel::Warn, + source: NotificationSource::Compactor, + message: "compaction failed".into(), + timestamp_ms: 1_700_000_000_000, + }); + let json = serde_json::to_string(&event).unwrap(); + let parsed: serde_json::Value = serde_json::from_str(&json).unwrap(); + assert_eq!(parsed["event"], "notification"); + assert_eq!(parsed["data"]["level"], "warn"); + assert_eq!(parsed["data"]["source"], "compactor"); + assert_eq!(parsed["data"]["message"], "compaction failed"); + assert_eq!(parsed["data"]["timestamp_ms"], 1_700_000_000_000i64); + } + #[test] fn event_error_format() { let event = Event::Error { diff --git a/crates/tui/src/app.rs b/crates/tui/src/app.rs index c391e825..217b9dae 100644 --- a/crates/tui/src/app.rs +++ b/crates/tui/src/app.rs @@ -1,4 +1,4 @@ -use protocol::{Event, Greeting, Method}; +use protocol::{Event, Greeting, Method, NotificationLevel, NotificationSource}; pub struct App { pub pod_name: String, @@ -35,6 +35,10 @@ pub enum MessageKind { Tool, Error, TurnStats, + /// Pod → user notification, Warn level. + NoticeWarn, + /// Pod → user notification, Error level. + NoticeError, } impl App { @@ -166,6 +170,21 @@ impl App { self.current_tool = None; } Event::ToolCallArgsDelta { .. } => {} + Event::Notification(notification) => { + let kind = match notification.level { + NotificationLevel::Warn => MessageKind::NoticeWarn, + NotificationLevel::Error => MessageKind::NoticeError, + }; + let prefix = match notification.level { + NotificationLevel::Warn => "[notice]", + NotificationLevel::Error => "[notice error]", + }; + let source = notification_source_label(notification.source); + self.output_queue.push(OutputItem::Padded( + kind, + format!("{prefix} {source}: {}", notification.message), + )); + } Event::History { items, greeting } => { self.restore_history(&items); if self.turn_index == 0 { @@ -298,6 +317,15 @@ impl App { } } +fn notification_source_label(source: NotificationSource) -> &'static str { + match source { + NotificationSource::Pod => "pod", + NotificationSource::Worker => "worker", + NotificationSource::Compactor => "compactor", + NotificationSource::AgentsMd => "AGENTS.md", + } +} + pub fn fmt_tokens(n: u64) -> String { if n >= 1_000_000 { format!("{:.1}M", n as f64 / 1_000_000.0) diff --git a/crates/tui/src/ui.rs b/crates/tui/src/ui.rs index 6e477858..cebf0855 100644 --- a/crates/tui/src/ui.rs +++ b/crates/tui/src/ui.rs @@ -232,6 +232,14 @@ pub fn kind_style(kind: &MessageKind) -> Style { MessageKind::Tool => Style::default().fg(Color::Cyan), MessageKind::Error => Style::default().fg(Color::Red), MessageKind::TurnStats => Style::default().fg(Color::DarkGray), + MessageKind::NoticeWarn => Style::default() + .fg(Color::Black) + .bg(Color::Yellow) + .add_modifier(Modifier::BOLD), + MessageKind::NoticeError => Style::default() + .fg(Color::White) + .bg(Color::Red) + .add_modifier(Modifier::BOLD), } } diff --git a/tickets/pod-factory.md b/tickets/pod-factory.md new file mode 100644 index 00000000..cc42f46a --- /dev/null +++ b/tickets/pod-factory.md @@ -0,0 +1,140 @@ +# Pod Factory: 設定カスケードとプロンプト資産による Pod 自動生成 + +## 背景 + +現状、Pod を起動するには `test_pod.local.toml` のような完全な `PodManifest` TOML を手書きする必要がある。1 人のユーザーが1 つのエージェントを試験運用するには十分だが、Insomnia が狙う「複数のエージェントが独立プロセスとして spawn されて自律的に動く」世界観では、**Pod のライフサイクル全体が自動化可能でなければならない**。そのためには、Pod の**作成自体**も自動化可能である必要がある。 + +手書きマニフェストには以下の問題がある: + +- 1 Pod = 1 ファイルで、Pod を動的に増やす用途にスケールしない +- 設定項目が多く（`worker.*` / `provider.*` / `scope.*` / `compaction.*` / `tool_output.*` 等）、毎回コピペしてわずかな差分だけ書き換える苦行になる +- system_prompt を TOML 文字列に埋め込む形はプロンプト資産の再利用性が低い +- Pod の起動条件の**共通部分**（プロバイダ・モデル・デフォルトツール設定など）は本来一度書けば良いのに、毎回書かされる + +## ゴール + +Pod 作成を「**最終的に `PodManifest` を1 つ構築する問題**」として定式化し、その `PodManifest` を**カスケード + 差分上書き**で組み立てる基盤を提供する。手書きが必要な TOML は「ユーザー / プロジェクト単位の**デフォルト上書き**」だけに縮退させ、個別の Pod 起動ごとに人間が TOML を触らない状態を目指す。 + +プロンプトは手書きマニフェストに文字列を埋め込む方式をやめ、**テンプレート資産ライブラリ**として参照可能にする。 + +## 方針 + +### 同じ型で、層で上書きする + +- **解決後の型は現行の `manifest::PodManifest` のまま**。Pod 側の契約（`Pod::from_manifest`）は変更しない。 +- カスケードは `PodManifest` より上の「部分的な `PodManifest` を層ごとに保持し、順番にマージして最終形を作る」層として設計する。 +- 各層は**部分形**を持てる（全フィールドを埋める必要はない）。存在するフィールドだけが下層を上書きする。 + +### カスケードの層 + +優先順位が低い方から高い方へ: + +1. **ビルトインのデフォルト**: コードに焼き込んだ基本値（現在 `PodManifest` 各フィールドの `#[serde(default)]` や `Default` 実装に散っているものを集約） +2. **ユーザー設定**: `~/.config/insomnia/config.toml` など。ユーザー個人のプロバイダ指定・デフォルトモデル・常用ツール設定等を書く +3. **プロジェクト設定**: プロジェクト直下の `.insomnia/config.toml` など。プロジェクト固有の scope・compaction 設定・system_prompt のベース等を書く +4. **プログラマティック上書き**: Pod 生成を呼ぶコード（GUI / CLI / 別 Pod からの spawn 等）が渡す `PodManifestOverlay` 的な部分形。ここで `pod.name` や `pod.pwd` のような**その Pod に固有の値**を与える + +各層とも人間が書くときは `PodManifest` と同じ TOML スキーマで書く（サブセット可）。 + +### マージのセマンティクス + +- **スカラー** (`String`, `u32`, `bool` 等): 上層が存在すれば丸ごと置換 +- **Option 型**: 上層が `Some` なら置換、`None` なら据え置き +- **マップ** (例: `tool_output.per_tool`): キー単位でマージ、同一キーは上層優先 +- **リスト** (例: `scope.allow` / `scope.deny`): **原則置換**（append にすると下層の意図しないルールが漏れる危険）。ただし append したいケースはあるので、設計時に decoration の形式（例: `scope.allow_extra` など）を別途検討 +- 未知フィールドは manifest エラーにせずログ警告 + +### プロンプト資産ライブラリ + +- プロンプトは TOML 文字列ではなく**ファイルとして管理**する。 +- 検索パスはカスケードと対応した3層: + 1. **ビルトイン**: バイナリに同梱されたデフォルトプロンプト（`coder` / `reviewer` / `planner` 等、設計時に選定） + 2. **ユーザー**: `~/.config/insomnia/prompts/*.md` 等 + 3. **プロジェクト**: `.insomnia/prompts/*.md` 等 +- 同名があれば**上層が優先**。 +- 既存の `SystemPromptTemplate`（minijinja ベース）のローダを拡張し、テンプレート内から他のプロンプトを `{% include "coder" %}` / `{% import "planner" as p %}` のように参照できるようにする。 +- 層の異なる同名プロンプトを合成するための include 先解決は上記優先順位に従う。 + +### 設定値のテンプレート参照は扱わない + +`worker.max_tokens = "{{ env.INSOMNIA_MAX_TOKENS }}"` のような**設定値の中でテンプレートを展開する機能は本チケットの範囲外**とする。テンプレートエンジンはプロンプト本文の組み立てだけに限定する。設定値の動的化が必要になった時点で別チケットで検討する。 + +### プログラマティック Pod 作成 API + +- `Pod::from_manifest(path)` の隣に、カスケード解決を経由する生成経路を追加する。イメージ: + + ```rust + // 層を明示的に指定して最終形を得る + let manifest = PodFactory::new() + .with_user_config(user_config_path)? // absent OK + .with_project_config(project_root)? // absent OK + .with_overlay(overlay_toml_or_struct) // programmatic + .resolve()?; // -> PodManifest + Pod::from_manifest(manifest, store).await?; + ``` + +- 細かい形状は設計時に詰める（builder 型 vs 関数型、`overlay` を TOML 文字列か型付きか等）。 +- CLI からは `insomnia spawn --overlay '...'` 相当で同じ経路を叩く想定。 + +## 要件 + +### カスケード基盤 + +- ユーザー設定・プロジェクト設定・プログラマティック overlay を順に重ねた結果が `PodManifest` として取れる。 +- 各層が部分形を許容する（`pod.pwd` だけ書いてあっても良い等）。 +- マージセマンティクスが**フィールドごとに定義**され、テストされる（スカラー / Option / マップ / リスト）。 +- 層が全て空でも**ビルトインデフォルト単体で有効な manifest にならない**（少なくとも `pod.pwd` と `provider` と `scope.allow` は上位層で与える必要がある）。その旨を resolve 時のエラーで明示する。 + +### プロンプト資産ライブラリ + +- 3層の検索パスでプロンプトファイルを解決できる。 +- 同名プロンプトは上層優先で解決される。 +- `SystemPromptTemplate` の minijinja `Environment` にカスタムローダを仕込み、`{% include "name" %}` / `{% import "name" as x %}` で資産を参照できる。 +- プロンプト資産自体もテンプレートとして評価され、現行の `SystemPromptContext`（`now` / `cwd` / `scope` / `tools` / `files` 等）と同じ変数が見える。 + +### プログラマティック Pod 作成 + +- 既存の `Pod::from_manifest` を壊さず、追加経路として `PodFactory` 系の API を提供する。 +- TUI / GUI / daemon 等の上位クライアントが、TOML ファイルパスではなく**オーバーレイ + 設定ディレクトリパス**を渡すだけで Pod を起動できる。 + +### ドキュメント + +- カスケード層の優先順位・マージ規則を `docs/` にまとめる。 +- ユーザー設定 / プロジェクト設定ファイルの**最小例**と**全オプション例**を残す。 + +## 設計で決めること + +- **ユーザー設定のパス**: `~/.config/insomnia/config.toml` か、XDG 非準拠のパスも許容するか。環境変数で上書きできるか。 +- **プロジェクト設定の場所**: プロジェクトルートの `.insomnia/config.toml` か、別の命名か。サブディレクトリから起動したときの discovery（上位ディレクトリ探索）の挙動。 +- **プロジェクトルートの判定**: 明示指定 vs `.git` や `.insomnia/` で自動検出 +- **preset の概念を入れるか**: 名前付きの overlay セット（例: `insomnia spawn coder`）を導入するか。導入する場合、preset はユーザー設定内に `[preset.coder]` として持つか、個別ファイル `~/.config/insomnia/presets/coder.toml` として持つか +- **リストフィールドのマージ方針**: 置換 only にするか、append 用の別フィールド (`scope.allow_extra` 等) を用意するか +- **ビルトインプロンプトの初期ラインナップ**: どの役割をデフォルトで同梱するか、どこに置くか（`crates/pod/assets/prompts/*.md` を `include_str!` で埋め込む等） +- **プロンプト資産のファイル形式**: `.md` か `.txt` か、拡張子省略可能にするか、フロントマター（YAML/TOML）で引数デフォルトを持たせるか +- **プロンプト include 時の context 伝搬**: 親テンプレートの変数を include 先でも見えるようにするか、明示的に `with` で渡させるか +- **エラー戦略**: 上層で書かれた未知フィールドや型ミスマッチをどこまで寛容に扱うか +- **既存の `Pod::from_manifest(path)` とのインターフェース整理**: 廃止するか、内部的に PodFactory に委譲するか +- **CLI コマンド名**: `insomnia spawn` / `insomnia pod new` / その他 + +## 完了条件 + +- `PodManifest` の最終形を層のマージで構築する `PodFactory`（または同等の仕組み）が実装され、マージセマンティクスの単体テストが通る。 +- ユーザー設定・プロジェクト設定・プログラマティック overlay のすべての層を使う end-to-end テストで、Pod が TOML ファイルパスを一切渡さずに起動できる。 +- プロンプト資産ライブラリを経由して system_prompt が組み立てられ、`{% include "ビルトイン名" %}` で同梱プロンプトを参照できることをテストで確認できる。 +- ユーザー設定ファイル / プロジェクト設定ファイルのドキュメントが `docs/` に存在する。 +- 既存の `Pod::from_manifest(path)` 経路が動き続ける（回帰させない）。 + +## 他チケットとの関係 + +- `tickets/native-gui-mvp.md`: 現状「manifest ファイルを選ぶ UI」を含むが、本チケット完了後はその UI が「preset 選択 + overlay 入力」に置き換わる想定。native-gui-mvp 実装時に本チケットの API を使うか、先に文字列パス渡しで済ませて後から差し替えるかは別途判断 +- `tickets/tui-pod-spawn-ui.md`: 同上。Pod spawn UI は本チケットが提供する API の上に構築される +- `tickets/protocol-design.md`: Pod ↔ Client protocol 自体は変わらない。spawn 要求を protocol に載せるかどうかは protocol-design 側で検討 +- `docs/system-prompt-template.md` / `crates/pod/src/system_prompt.rs`: プロンプト資産ライブラリはこの minijinja 基盤の拡張として実装される + +## 範囲外 + +- **設定値の中のテンプレート展開**（`max_tokens = "{{ env.X }}"` のような動的値）。プロンプト本文のテンプレート展開のみを扱う +- **GUI 内での設定ファイル編集 UI**。編集は人間がエディタで TOML を書くだけ（あくまで「Pod 生成時に手書きしない」ことを目指す） +- **チーム共有・同期**。ユーザー設定とプロジェクト設定は各自・各リポジトリ単位で管理される +- **秘密情報管理**（API キー等）。既存の `api_key_file` 方式を維持する +- **設定値の型バリデーション強化**（JSON Schema など）。現行の serde ベースで十分な範囲に留める diff --git a/tickets/tui-notification-channel.md b/tickets/tui-notification-channel.md index ce786e31..91c6a439 100644 --- a/tickets/tui-notification-channel.md +++ b/tickets/tui-notification-channel.md @@ -1,5 +1,10 @@ # TUI 通知チャネル: Warn/Error をユーザーに可視化 +## レビュー状態 + +初回レビュー実施済み。[tui-notification-channel.review.md](tui-notification-channel.review.md) を参照。 +コア要件は達成。残る指摘は (1) `Notifier::buffer` の無制限成長、(2) TUI 側の表示強度（履歴行に紛れるか別立てで見落とさない位置に出すか）の 2 点で、いずれも user 判断待ち。 + ## 背景 Pod/Worker 層は現在、通知すべき事象（compaction 失敗、AGENTS.md 読み取り失敗、ツール出力の切り詰め、将来追加される様々な前処理エラー等）をすべて `tracing::warn!` で出している。TUI はこのログを受け取る仕組みを持たないため、**ユーザーは何も気づかないまま Pod が縮退動作している状態**になりうる。 diff --git a/tickets/tui-notification-channel.review.md b/tickets/tui-notification-channel.review.md new file mode 100644 index 00000000..05b4e821 --- /dev/null +++ b/tickets/tui-notification-channel.review.md @@ -0,0 +1,107 @@ +# レビュー: TUI 通知チャネル + +対象差分: `crates/pod/src/{notifier,pod,controller,agents_md,lib,socket_server}.rs`, `crates/llm-worker/src/worker.rs`, `crates/protocol/src/lib.rs`, `crates/tui/src/{app,ui}.rs`（いずれも未コミット） + +## 要件達成状況 + +| 要件 | 状態 | +|---|---| +| Pod 層が型付き通知を発行する API を持つ | ✅ `Notifier::notify(level, source, message)`、`PodHandle::notify` / `Pod::notify` ラッパ | +| `tracing` とは別系統 | ✅ 既存 `tracing::warn!` は並存、通知は `Notifier` 経由のみ | +| 構造化型（level / source / message / timestamp） | ✅ `protocol::Notification` に全4項目。timestamp は unix ms の i64 | +| レベルは Warn / Error（Info は設計判断） | ✅ Info は除外（設計判断として妥当） | +| 発生源の列挙（Pod / Worker / Compactor / Tool 境界等） | ✅ `NotificationSource::{Pod, Worker, Compactor, AgentsMd}`。Tool 境界は Worker に集約 | +| TUI が受信して表示する | 🟡 表示はする（`MessageKind::NoticeWarn/Error` + 色 + bold）が、**ticket が想定した「一時表示・通知ペイン」レベルには到達していない**。後述 | +| Error と Warn の視覚的区別 | ✅ Yellow bold / Red bold + `[notice]` / `[notice error]` prefix | +| 通知履歴が見られる | 🟡 `output_queue` → scrollback に残るのみ。専用ペインでの閲覧は無い | +| 新着通知の一時表示 | 🟡 普通のメッセージ行として積まれるだけ、トースト / ステータスバー常駐は無し | +| 複数通知の重ね合わせ | 🟡 単純 append、特段の配慮は無し | +| 既存 `tracing::warn!` の置換（compaction 失敗） | ✅ `pod.rs` の mid-run / post-run 両経路で notify。並行して tracing も残る | +| 既存 `tracing::warn!` の置換（ツール出力切り詰め） | ✅ `worker.rs` が `on_warning` コールバック経由で Controller → Notifier に流す | +| 既存 `tracing::warn!` の置換（AGENTS.md） | ✅ `read_agents_md` が `AgentsMdResult { body, warnings }` を返し、`pod.rs` で notify | + +**コア要件は達成**。「TUI の表示方法」は設計議論を含む項目で、ticket の "設計で決めること" に「トースト / ステータスバー / 通知ペイン / その組合せ」と列挙されていた部分を、実装者は**「履歴内の区別された行」に絞った**と読める。これは最小実装としては筋が通るが、ticket 本文の「見落としにくい位置に一時的に表示」という表現とは**乖離**があり、判断を user に返すべき。 + +## アーキテクチャ統合 + +### 良い点 + +- **`Notifier` の race-free 購読**: `subscribe_with_snapshot` が `buffer` の mutex を保持したまま `event_tx.subscribe()` を呼び、snapshot をクローンしてから返すことで、「通知が snapshot と live の両方に現れる」「どちらからも漏れる」の両方を同時に防いでいる。`notifier.rs` のテスト `subscribe_snapshot_and_live_do_not_overlap` で設計意図を lock-in している。late subscriber 対応は本チケットの肝であり、最もよく出来ている部分。 +- **層の分離**: Worker は `on_warning(Box)` というタイプ消去されたコールバックを受ける形にし、`protocol::Notification*` 型に依存していない。Controller 側で closure に notifier をキャプチャして橋渡しする。Worker が protocol に依存せずに済んでおり、llm-worker は低レベル基盤のままという方針（memory）とも整合。 +- **`read_agents_md` の pure 分離**: 以前は `Option` + 直接 `tracing::warn!` だったが、`AgentsMdResult { body, warnings }` を返す形に変更され、呼び出し側が副作用（notify）を担当する。pure function + 副作用集約の分離として綺麗。 +- **既存 broadcast channel への相乗り**: `Event::Notification(Notification)` という新バリアントとして既存の `broadcast::Sender` に載せたことで、新しい通信経路を作らずに済んでいる。`socket_server` 側の配線変更も `subscribe_with_snapshot` の snapshot を prelude として書き出し、以降は既存 loop に合流する、という自然な形。 +- **`Pod::attach_notifier` パターン**: Controller が Pod の construction 後に notifier を差し込む（`Pod::new` 自体は notifier を持たない）ため、Pod 直接 new の tests でも Notifier が不要。`None` のときは `Pod::notify` が no-op になる。 + +### 懸念 1: 🟡 `Notifier::buffer` が無制限に伸びる + +```rust +struct Inner { + event_tx: broadcast::Sender, + buffer: Mutex>, +} +``` + +セッションが長寿命かつ通知が頻発するケース（compaction 失敗がループするとか、ツール出力切り詰めが毎ターン起きるとか）で、`buffer` は単調増加する。新規クライアントが接続した瞬間に `subscribe_with_snapshot` が全部クローンするので、**1 接続あたりのメモリ消費と初期送信コストも比例して増える**。 + +ticket には明示的な上限要件は無いが、実運用での**メモリ健全性**として上限を設けるべき。たとえば: + +- 上限件数 (例: 256 件) でリング化（最古から落とす） +- 時間窓（直近 N 分） +- 落とした件数だけ "[N older notifications elided]" の synthetic notification を先頭に置く + +**判断**: 要検討。後続チケットとして切るか、本チケットの範囲で追補するか。 + +### 懸念 2: 🟡 TUI 側の表示が ticket 要件の minimum interpretation + +ticket 要件: +> - 新着通知はユーザーが見落としにくい位置に**一時的**に表示される（トースト / ステータスバー等） +> - 履歴が見られる（キーバインドで通知ペインを開ける等） + +実装: +- `MessageKind::NoticeWarn/Error` として通常のメッセージ行と同じ `output_queue` に積む +- Yellow/Red の bold + `[notice]` prefix で視覚的に区別 +- トースト・ステータスバー常駐・通知ペインは無し + +ユーザーが会話に集中していてスクロールが別位置にあった場合、新着通知は画面外に流れて気付けない可能性が高い。 + +一方、ticket の "設計で決めること" には 4 択が並んでおり、実装者が minimum viable として「履歴に色付きで積む」を選んだという解釈もできる。 + +**判断**: user が「これで良い」と言えば OK。「やはり見落とす」となれば別タスクとして追加実装（status 行 1 段拡張でラスト通知を pin する、など）が必要。 + +### 懸念 3: 🟢 `NotificationSource` に Pod 名が入らない + +現状 `NotificationSource` はカテゴリだけ持ち、Pod 名や具体的な tool 名は `message` 本文に埋め込む設計。単一 Pod 前提ではこれで十分。将来 `tickets/native-gui-mvp.md` で GUI が複数 Pod を spawn するようになると「どの Pod の通知か」がメッセージパースでしか分からなくなる。 + +**判断**: 不問。複数 Pod 対応のチケット（将来）で `Notification` に Pod 名フィールドを追加するのが自然。現時点で先回りする必要は無い。 + +### 懸念 4: 🟢 `PodHandle::subscribe` の用途 + +以前は `handle.subscribe()` を直接呼んで broadcast::Receiver を得ていたところが、今は `handle.notifier.subscribe_with_snapshot()` 経由になった。`PodHandle::subscribe` 自体はまだ存在しており、socket_server 以外に呼び出し元があるかは未確認。無ければ将来削除可能。 + +**判断**: 不問。クリーンアップは別途。 + +## 完了条件照合 + +- [x] Pod 層が型付き通知を発行する API を持つ +- [x] TUI がその通知を受信して表示する +- [~] 履歴保存 — 一応 scrollback / `Notifier::buffer` には残るが、ticket 本文の「セッション単位で履歴を見られる」は minimal な達成 +- [~] 手動テストで TUI 画面上に現れることの確認 — コードレベルでは通るが、実機確認の記述は無い（これは受け入れテストの話） + +## テスト + +- `notifier.rs` の 3 ケース（broadcast / late subscriber snapshot / snapshot-live non-overlap）は設計要点を的確にカバー +- `protocol/lib.rs` で `event_notification_format` が JSON 表現を lock-in +- `agents_md.rs` のテストは `AgentsMdResult` 変更に追従し、`non_utf8_surfaces_warning` が新規に追加されて warning 経路をカバー +- Controller / Pod / socket_server レベルの integration test は無し。`Notifier` の単体テストで十分と割り切った判断と見える + +## 結論 + +**コア要件は達成、アーキテクチャは筋が良い**。特に race-free subscribe と層の分離は見事。 + +残る指摘: + +1. 🟡 **buffer 無制限**: 実運用でメモリ単調増加の可能性。上限の検討要 +2. 🟡 **TUI 表示の強度**: ticket 文面からは「通知は見落とされないべき」と読めるが、実装は履歴行に紛れる最小形。user 判断待ち +3. 🟢 **Pod 名フィールド** / 🟢 **`PodHandle::subscribe` の残存**: 不問 + +**受け入れ可否**: 指摘1・2について user 判断。採否次第で「このまま受け入れ」「buffer 上限だけ追補」「TUI 表示も強化」の 3 パスに分岐する。