use std::collections::HashSet;
use std::sync::Arc;
use axum::Json;
use axum::extract::rejection::{JsonRejection, QueryRejection};
use axum::extract::{Query, State};
use axum::response::IntoResponse;
use chrono::{DateTime, Utc};
use second_brain_core::redact::redact_for_store;
use second_brain_core::schema::{AGENT_NOTE_SOURCE, Memory};
use second_brain_core::sqlite_store::{AgentNote, NoteKind, SqliteStore};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
use super::memory::{Written, parse_client_id, parse_session_at, replayed, store_explicit};
use super::{bad_request, internal_error};
use crate::AppState;
#[derive(Deserialize)]
pub(super) struct NoteRequest {
id: Option<String>,
session_id: Option<String>,
kind: Option<String>,
decision: Option<String>,
reason: Option<String>,
dead_ends: Option<Vec<String>>,
open_items: Option<Vec<String>>,
blocked_on_user: Option<Vec<String>>,
project: Option<String>,
session_at: Option<String>,
}
struct NoteWrite {
client_id: Option<Uuid>,
session_id: String,
note: AgentNote,
project: Option<String>,
session_at: Option<DateTime<Utc>>,
}
#[derive(Serialize)]
struct NoteReply {
id: String,
kind: NoteKind,
duplicate: bool,
}
fn parse_kind(kind: Option<&str>) -> Result<NoteKind, String> {
let Some(name) = kind else {
return Ok(NoteKind::default());
};
NoteKind::parse(name).ok_or_else(|| {
let valid: Vec<&str> = NoteKind::ALL.iter().map(|kind| kind.as_str()).collect();
format!("unknown kind '{name}'; valid values: {}", valid.join(", "))
})
}
fn trimmed(value: Option<String>) -> Option<String> {
value
.map(|value| value.trim().to_string())
.filter(|value| !value.is_empty())
}
fn required_session_id(session_id: Option<String>) -> Result<String, String> {
trimmed(session_id).ok_or_else(|| "session_id is required".to_string())
}
fn redacted_all(items: Vec<String>) -> Vec<String> {
items.iter().map(|item| redact_for_store(item)).collect()
}
fn redacted(mut note: AgentNote) -> AgentNote {
note.decision = redact_for_store(¬e.decision);
note.reason = redact_for_store(¬e.reason);
note.dead_ends = redacted_all(note.dead_ends);
note.open_items = redacted_all(note.open_items);
note.blocked_on_user = redacted_all(note.blocked_on_user);
note
}
fn validated(req: NoteRequest) -> Result<NoteWrite, String> {
let session_id = required_session_id(req.session_id)?;
let mut note = AgentNote::new(
parse_kind(req.kind.as_deref())?,
req.decision.unwrap_or_default(),
);
note.reason = req.reason.unwrap_or_default();
note.dead_ends = req.dead_ends.unwrap_or_default();
note.open_items = req.open_items.unwrap_or_default();
note.blocked_on_user = req.blocked_on_user.unwrap_or_default();
let note = note.normalized();
if note.decision.is_empty() {
return Err("decision is required".to_string());
}
Ok(NoteWrite {
client_id: parse_client_id(req.id.as_deref())?,
session_id,
note: redacted(note),
project: req.project,
session_at: parse_session_at(req.session_at.as_deref())?,
})
}
const UUID_LEN: usize = 36;
fn is_hyphenated_uuid(window: &[u8]) -> bool {
window.iter().enumerate().all(|(i, b)| match i {
8 | 13 | 18 | 23 => *b == b'-',
_ => b.is_ascii_hexdigit(),
})
}
fn cited_ids<'a>(texts: impl IntoIterator<Item = &'a str>) -> Vec<Uuid> {
let mut seen = HashSet::new();
let mut ids = Vec::new();
for text in texts {
let bytes = text.as_bytes();
let mut start = 0;
while start + UUID_LEN <= bytes.len() {
let end = start + UUID_LEN;
let standalone = (start == 0 || !bytes[start - 1].is_ascii_alphanumeric())
&& bytes.get(end).is_none_or(|b| !b.is_ascii_alphanumeric());
if standalone
&& is_hyphenated_uuid(&bytes[start..end])
&& let Ok(id) = Uuid::parse_str(&text[start..end])
{
if seen.insert(id) {
ids.push(id);
}
start = end;
} else {
start += 1;
}
}
}
ids
}
fn cited_memories(write: &NoteWrite) -> Vec<Uuid> {
let note = &write.note;
let texts = [note.decision.as_str(), note.reason.as_str()]
.into_iter()
.chain(note.dead_ends.iter().map(String::as_str))
.chain(note.open_items.iter().map(String::as_str))
.chain(note.blocked_on_user.iter().map(String::as_str));
let own = [write.client_id, Uuid::parse_str(&write.session_id).ok()];
let mut ids = cited_ids(texts);
ids.retain(|id| !own.contains(&Some(*id)));
ids
}
fn store_note(state: &AppState, write: NoteWrite) -> anyhow::Result<Written> {
let memory_type = write.note.kind.memory_type();
if let Some(written) = replayed(&state.sqlite, write.client_id, memory_type)? {
return Ok(written);
}
let memory = Memory::new(
write.note.render(),
memory_type,
AGENT_NOTE_SOURCE.to_string(),
write.session_id,
)
.with_project_path(write.project)
.with_machine_id(state.machine.id.clone());
store_explicit(state, memory, write.client_id, write.session_at, &[])
}
pub(super) async fn write_note(
State(state): State<Arc<AppState>>,
req: Result<Json<NoteRequest>, JsonRejection>,
) -> axum::response::Response {
let write = match req
.map_err(|rejection| rejection.body_text())
.and_then(|Json(req)| validated(req))
{
Ok(write) => write,
Err(message) => return bad_request(message),
};
let kind = write.note.kind;
let cited = cited_memories(&write);
let result = tokio::task::spawn_blocking(move || {
let written = store_note(&state, write)?;
if matches!(written, Written::Stored { .. }) && !cited.is_empty() {
state.health.memories_used(&cited, Utc::now());
}
Ok::<_, anyhow::Error>(written)
})
.await;
let (id, duplicate) = match result {
Ok(Ok(Written::Stored { id, .. })) => (id, false),
Ok(Ok(Written::Replayed { id, .. })) => (id, true),
Ok(Err(e)) => return internal_error(e),
Err(e) => return internal_error(e),
};
Json(NoteReply {
id: id.to_string(),
kind,
duplicate,
})
.into_response()
}
const DEFAULT_PROJECT_NOTES: usize = 10;
const MAX_PROJECT_NOTES: usize = 50;
#[derive(Deserialize)]
pub(super) struct NotesQuery {
session_id: Option<String>,
project: Option<String>,
kind: Option<String>,
limit: Option<String>,
since: Option<String>,
}
enum NotesLookup {
Session(String),
Project {
project: String,
limit: usize,
since: Option<DateTime<Utc>>,
},
}
fn project_limit(limit: Option<&str>) -> Result<usize, String> {
let Some(text) = limit else {
return Ok(DEFAULT_PROJECT_NOTES);
};
match text.parse::<usize>() {
Ok(limit) if limit > 0 => Ok(limit.min(MAX_PROJECT_NOTES)),
_ => Err(format!("limit must be a positive integer, got '{text}'")),
}
}
fn parse_since(since: Option<&str>) -> Result<Option<DateTime<Utc>>, String> {
let Some(text) = since else {
return Ok(None);
};
DateTime::parse_from_rfc3339(text)
.map(|at| Some(at.with_timezone(&Utc)))
.map_err(|_| format!("since must be an RFC 3339 time, got '{text}'"))
}
fn notes_lookup(q: NotesQuery) -> Result<(NotesLookup, Option<NoteKind>), String> {
let kind = q.kind.as_deref().map(|k| parse_kind(Some(k))).transpose()?;
let lookup = match (trimmed(q.session_id), trimmed(q.project)) {
(Some(_), Some(_)) => return Err("pass session_id or project, not both".to_string()),
(None, None) => return Err("session_id or project is required".to_string()),
(Some(_), None) if q.limit.is_some() => {
return Err("limit applies only to a project lookup".to_string());
}
(Some(_), None) if q.since.is_some() => {
return Err("since applies only to a project lookup".to_string());
}
(Some(session_id), None) => NotesLookup::Session(session_id),
(None, Some(project)) => NotesLookup::Project {
project,
limit: project_limit(q.limit.as_deref())?,
since: parse_since(q.since.as_deref())?,
},
};
Ok((lookup, kind))
}
#[derive(Serialize)]
struct NoteResponse {
id: String,
#[serde(flatten)]
note: AgentNote,
session_id: String,
project: Option<String>,
session_at: Option<String>,
created_at: String,
}
fn project_notes_since(
sqlite: &SqliteStore,
project: &str,
since: DateTime<Utc>,
kind: Option<NoteKind>,
limit: usize,
) -> anyhow::Result<Vec<(Memory, AgentNote)>> {
let notes = sqlite.notes_created_between(since, Utc::now(), Some(project))?;
Ok(notes
.into_iter()
.filter(|(_, note)| kind.is_none_or(|kind| note.kind == kind))
.take(limit)
.collect())
}
fn note_response((memory, note): (Memory, AgentNote)) -> NoteResponse {
NoteResponse {
id: memory.id.to_string(),
note,
session_id: memory.source_id,
project: memory.project_path,
session_at: memory.session_at.map(|at| at.to_rfc3339()),
created_at: memory.created_at.to_rfc3339(),
}
}
pub(super) async fn list_notes(
State(state): State<Arc<AppState>>,
query: Result<Query<NotesQuery>, QueryRejection>,
) -> axum::response::Response {
let lookup = query
.map_err(|rejection| rejection.body_text())
.and_then(|Query(q)| notes_lookup(q));
let (lookup, kind) = match lookup {
Ok(lookup) => lookup,
Err(message) => return bad_request(message),
};
let result = tokio::task::spawn_blocking(move || match lookup {
NotesLookup::Session(session_id) => state.sqlite.notes_for_session(&session_id, kind),
NotesLookup::Project {
project,
limit,
since: None,
} => state.sqlite.latest_notes_for_project(&project, kind, limit),
NotesLookup::Project {
project,
limit,
since: Some(since),
} => project_notes_since(&state.sqlite, &project, since, kind, limit),
})
.await;
match result {
Ok(Ok(notes)) => {
let notes: Vec<NoteResponse> = notes.into_iter().map(note_response).collect();
Json(serde_json::json!({ "notes": notes })).into_response()
}
Ok(Err(e)) => internal_error(e),
Err(e) => internal_error(e),
}
}
#[cfg(test)]
mod tests {
use super::*;
const A: &str = "0b6f2c1e-6d0a-4e8b-9a51-2f3c4d5e6f70";
const B: &str = "9F1E2D3C-4B5A-4978-8695-A4B3C2D1E0F9";
fn ids(texts: &[&str]) -> Vec<Uuid> {
cited_ids(texts.iter().copied())
}
fn uuid(text: &str) -> Uuid {
Uuid::parse_str(text).unwrap()
}
#[test]
fn cited_ids_finds_each_standalone_hyphenated_uuid_once() {
let (a, b) = (uuid(A), uuid(B));
let cases: Vec<(Vec<String>, Vec<Uuid>)> = vec![
(vec![String::new()], vec![]),
(vec!["no ids here".to_string()], vec![]),
(vec![A.to_string()], vec![a]),
(vec![format!("used {A}, then {B}.")], vec![a, b]),
(vec![format!("[{B}] and ({A})")], vec![b, a]),
(vec![format!("{A} {}", A.to_uppercase())], vec![a]),
(
vec![format!("see {A}"), format!("again {A} and {B}")],
vec![a, b],
),
(vec![format!("{A}{B}")], vec![]),
(vec![format!("x{A}")], vec![]),
(vec![format!("{A}0")], vec![]),
(vec![format!("memory-{A}-x")], vec![a]),
(vec![A.replace('-', "")], vec![]),
(vec![A[..35].to_string()], vec![]),
(vec![A.replacen('0', "g", 1)], vec![]),
(vec![format!("\u{e9}{A}\u{e9}")], vec![a]),
];
for (texts, expected) in cases {
let texts: Vec<&str> = texts.iter().map(String::as_str).collect();
assert_eq!(ids(&texts), expected, "{texts:?}");
assert_eq!(ids(&texts), ids(&texts), "{texts:?}");
}
}
#[test]
fn cited_ids_scans_a_long_near_miss_run_in_linear_time() {
let text = "0b6f2c1e-6d0a-4e8b-9a51-".repeat(20_000);
let started = std::time::Instant::now();
assert!(ids(&[text.as_str()]).is_empty());
assert!(
started.elapsed() < std::time::Duration::from_secs(5),
"{:?}",
started.elapsed()
);
}
fn write(note: AgentNote, client_id: Option<Uuid>, session_id: &str) -> NoteWrite {
NoteWrite {
client_id,
session_id: session_id.to_string(),
note,
project: None,
session_at: None,
}
}
#[test]
fn a_note_cites_ids_from_every_field_but_never_its_own_or_its_sessions() {
let (a, b) = (uuid(A), uuid(B));
let own = Uuid::new_v4();
let session = Uuid::new_v4();
let mut note = AgentNote::new(NoteKind::default(), format!("kept {A}"));
note.reason = format!("because {own}");
note.dead_ends = vec![format!("tried {session}")];
note.open_items = vec![format!("check {B}")];
note.blocked_on_user = vec![format!("ask about {A}")];
assert_eq!(
cited_memories(&write(note.clone(), Some(own), &session.to_string())),
vec![a, b]
);
assert_eq!(
cited_memories(&write(note, None, "not-a-uuid")),
vec![a, own, session, b]
);
}
}