Merge sessions module (Agent Sessions, Memory Bank)

This commit is contained in:
2026-10-24 04:37:00 +02:00
20 changed files with 3242 additions and 3 deletions
+520
View File
@@ -0,0 +1,520 @@
// Agent Sessions and Memory Bank: deterministic local checks only (names,
// ids, caps, validation before traffic, request bodies against the call
// table that tools/check_discovery.py verifies against Google's Discovery
// document). No scripted Google replies. The opt-in live probe at the end is
// read-only and gated on MOLO_LIVE_NET=1 plus a credential.
#include <algorithm>
#include <cstdlib>
#include <functional>
#include <iostream>
#include <memory>
#include <set>
#include <sstream>
#include "framework.h"
#include "clients/transports/http_transport.h"
#include "clients/transports/mock_transport.h"
#include "google/credentials.h"
#include "google/sessions/calls.h"
#include "google/sessions/caps.h"
#include "google/sessions/memory_bank.h"
#include "google/sessions/sessions.h"
using namespace molo::google;
using namespace molo::google::sessions;
using molo::clients::body::Json;
using molo::clients::transports::MockTransport;
namespace {
const char* kEngine = "projects/p1/locations/us-central1/reasoningEngines/e1";
struct Rig {
MockTransport* mock;
std::shared_ptr<GoogleClient> client;
explicit Rig(bool with_credential = true) {
auto t = std::make_unique<MockTransport>();
mock = t.get();
client = std::make_shared<GoogleClient>(
std::move(t), with_credential ? Credentials::bearer("tok") : nullptr);
}
};
std::set<std::string> words(const std::string& s) {
std::set<std::string> out;
std::istringstream in(s);
for (std::string w; in >> w;) out.insert(w);
return out;
}
// Every key of a built body must be a field the call table declares (and the
// discovery check proves exists in Google's request schema).
void keys_declared(const Json& body, Call call) {
std::set<std::string> allowed = words(spec_of(call).fields);
ASSERT_TRUE(body.is_object());
for (const auto& [key, value] : body.as_object()) {
(void)value;
if (!allowed.count(key)) FAIL("body key '" << key << "' not in the table row");
}
}
void invalid(const std::function<void()>& fn) {
try {
fn();
} catch (const GoogleError& e) {
ASSERT_EQ(e.http_status(), 400);
ASSERT_EQ(e.status(), std::string("INVALID_ARGUMENT"));
ASSERT_TRUE(e.service().empty()); // local validation, not upstream
return;
}
FAIL("expected INVALID_ARGUMENT");
}
} // namespace
TEST(sessions_table, every_call_has_one_well_formed_row) {
std::set<int> seen;
for (const CallSpec& row : kCalls) {
ASSERT_TRUE(seen.insert(static_cast<int>(row.call)).second);
std::string path = row.path;
ASSERT_TRUE(path.front() == '/');
ASSERT_EQ(std::count(path.begin(), path.end(), '{'), 1);
ASSERT_TRUE(path.find("{parent}") != std::string::npos ||
path.find("{name}") != std::string::npos);
std::string verb = row.verb;
ASSERT_TRUE(verb == "GET" || verb == "POST" || verb == "PATCH" || verb == "DELETE");
if (verb == "GET" || verb == "DELETE") ASSERT_EQ(std::string(row.fields), std::string());
}
ASSERT_EQ(seen.size(), static_cast<std::size_t>(Call::kCount));
ASSERT_EQ(expand(Call::kSessionAppendEvent, "x/y"), std::string("/x/y:appendEvent"));
ASSERT_EQ(expand(Call::kMemoryList, "x", "?a=b"), std::string("/x/memories?a=b"));
}
TEST(sessions_names, engine_name_parsing) {
EngineName e(kEngine);
ASSERT_EQ(e.project(), std::string("p1"));
ASSERT_EQ(e.location(), std::string("us-central1"));
ASSERT_EQ(e.engine(), std::string("e1"));
ASSERT_EQ(e.session("s-1"), std::string(kEngine) + "/sessions/s-1");
ASSERT_EQ(e.memory("m-1"), std::string(kEngine) + "/memories/m-1");
for (const char* bad : {"", "e1", "projects/p/locations/l/reasoningEngines",
"projects/p/locations/l/reasoningEngines/e/extra",
"projects/p/locations/l/engines/e",
"projects/P/locations/l/reasoningEngines/e",
"projects/p/locations/L/reasoningEngines/e",
"projects/p/locations/l/reasoningEngines/..",
"projects/p/locations/l/reasoningEngines/e?x=1",
"projects/p/locations//reasoningEngines/e"})
invalid([&] { EngineName n{std::string(bad)}; });
invalid([] { EngineName n{std::string(600, 'a')}; });
}
TEST(sessions_names, ids_and_checks) {
Check::session_id("a");
Check::session_id(std::string(63, 'a'));
Check::session_id("0-9-a");
for (const char* bad : {"", "A", "a_b", "a/b", "a b", "a.b"})
invalid([&] { Check::session_id(bad); });
invalid([] { Check::session_id(std::string(64, 'a')); });
Check::memory_id("m1");
for (const char* bad : {"", "1m", "-m", "m-", "M", "m_1"})
invalid([&] { Check::memory_id(bad); });
Check::ttl("86400s", 86400);
Check::ttl("90000.5s", 86400);
for (const char* bad : {"", "s", "86400", "1d", "-5s", "1.s", ".5s", "1.2.3s", "86399s"})
invalid([&] { Check::ttl(bad, 86400); });
invalid([] { Check::ttl("999999999999s", 1); });
Check::timestamp("t", "2025-01-31T11:30:00Z");
Check::timestamp("t", "2025-01-31T11:30:00.123+02:00");
for (const char* bad : {"", "yesterday", "2025-01-31 11:30:00Z", "2025/01/31T11:30:00Z"})
invalid([&] { Check::timestamp("t", bad); });
Check::scope({{"user_id", "42"}});
invalid([] { Check::scope({}); });
invalid([] { Check::scope({{"user_id", "*"}}); });
invalid([] { Check::scope({{"u*", "1"}}); });
invalid([] { Check::scope({{"u", ""}}); });
StringMap many;
for (int i = 0; i < 11; ++i) many["k" + std::to_string(i)] = "v";
invalid([&] { Check::scope(many); });
invalid([] { Check::expression("filter", std::string("a\nb")); });
invalid([] { Check::expression("filter", std::string(513, 'a')); });
invalid([] { Check::page_size(101, 100); });
invalid([] { Check::page_size(-1, 100); });
ASSERT_EQ(query_of({{"a", "x y"}, {"b", ""}, {"c", "1&2"}}),
std::string("?a=x%20y&c=1%262"));
}
TEST(sessions_bodies, session_create_patch_compact_event) {
SessionSpec spec;
spec.session_id = "chat-1";
spec.user_id = "u1";
spec.display_name = "d";
spec.labels = {{"env", "test"}};
Json state = Json::object();
state.set("k", Json("v"));
spec.session_state = state;
spec.ttl = "86400s";
spec.validate();
keys_declared(spec.to_json(), Call::kSessionCreate);
ASSERT_EQ(spec.to_json().find("userId")->as_string(), std::string("u1"));
SessionPatch patch;
patch.session_id = "chat-1";
patch.display_name = "new";
patch.update_mask = "displayName";
patch.validate();
keys_declared(patch.to_json(), Call::kSessionPatch);
patch.update_mask = "";
invalid([&] { patch.validate(); });
patch.update_mask = "a;b";
invalid([&] { patch.validate(); });
CompactRequest compact;
invalid([&] { compact.validate(); });
compact.summarization = true;
compact.validate();
keys_declared(compact.to_json(), Call::kSessionCompact);
ASSERT_EQ(compact.to_json().dump(), std::string("{\"compaction\":{\"summarization\":{\"mode\":\"AUTO\"}}}"));
SessionEvent ev;
ev.author = "user";
ev.invocation_id = "inv-1";
ev.timestamp = "2025-01-31T11:30:00Z";
ev.content = Content::user("hello");
Json actions = Json::object();
actions.set("escalate", Json(true));
ev.actions = actions;
ev.error_code = "E1";
ev.validate();
keys_declared(ev.to_json(), Call::kSessionAppendEvent);
SessionEvent round = SessionEvent::from_json(ev.to_json());
ASSERT_EQ(round.author, std::string("user"));
ASSERT_EQ(round.content->text(), std::string("hello"));
ev.invocation_id.clear();
invalid([&] { ev.validate(); });
}
TEST(sessions_bodies, session_validation_caps) {
SessionSpec spec;
invalid([&] { spec.validate(); }); // user_id required
spec.user_id = "u";
spec.validate();
spec.session_id = "BAD";
invalid([&] { spec.validate(); });
spec.session_id.clear();
spec.ttl = "3600s"; // below the 24 h minimum
invalid([&] { spec.validate(); });
spec.ttl.clear();
spec.session_state = Json(std::string("not an object"));
invalid([&] { spec.validate(); });
Json big = Json::object();
big.set("blob", Json(std::string(70 * 1024, 'x')));
spec.session_state = big;
invalid([&] { spec.validate(); });
spec.session_state = Json();
for (int i = 0; i < 21; ++i) spec.labels["l" + std::to_string(i)] = "v";
invalid([&] { spec.validate(); });
SessionEvent ev;
ev.author = "a";
ev.invocation_id = "i";
ev.timestamp = "2025-01-31T11:30:00Z";
ev.content = Content::user(std::string(300 * 1024, 'x'));
invalid([&] { ev.validate(); });
}
TEST(memory_bodies, generate_sources) {
MemoryGenerateRequest g;
g.scope = {{"user_id", "1"}};
g.contents = {Content::user("I like tea"), Content::model("noted")};
g.disable_consolidation = true;
g.allowed_topics = {Topic::managed("USER_PREFERENCES"), Topic::custom("hobbies")};
g.metadata["src"] = MetadataValue::of_string("chat");
g.metadata["score"] = MetadataValue::of_double(1.5);
g.metadata_merge_strategy = "MERGE";
g.time_zone = "Europe/Amsterdam";
g.revision.labels = {{"run", "1"}};
g.revision.ttl = "3600s";
g.validate();
Json body = g.to_json(kEngine);
keys_declared(body, Call::kMemoryGenerate);
ASSERT_TRUE(body.find("directContentsSource") != nullptr);
ASSERT_TRUE(body.find("vertexSessionSource") == nullptr);
ASSERT_EQ(body.find("directContentsSource")->find("events")->as_array().size(), std::size_t(2));
ASSERT_EQ(body.find("allowedTopics")->as_array()[1].find("customMemoryTopicLabel")->as_string(),
std::string("hobbies"));
g.source = MemoryGenerateRequest::Source::kSession;
g.session_id = "chat-1";
g.start_time = "2025-01-31T11:30:00Z";
g.validate();
Json sb = g.to_json(kEngine);
keys_declared(sb, Call::kMemoryGenerate);
ASSERT_EQ(sb.find("vertexSessionSource")->find("session")->as_string(),
std::string(kEngine) + "/sessions/chat-1");
g.source = MemoryGenerateRequest::Source::kDirectMemories;
invalid([&] { g.validate(); }); // none given
for (int i = 0; i < 6; ++i) g.direct_memories.push_back({"fact", {}});
invalid([&] { g.validate(); }); // Google allows at most 5
g.direct_memories.resize(5);
g.validate();
keys_declared(g.to_json(kEngine), Call::kMemoryGenerate);
g.source = MemoryGenerateRequest::Source::kContents;
g.contents.clear();
invalid([&] { g.validate(); });
g.contents = {Content::user(std::string(70 * 1024, 'x'))};
invalid([&] { g.validate(); });
g.contents = {Content::user("ok")};
g.scope = {{"u", "*"}};
invalid([&] { g.validate(); });
g.scope = {{"u", "1"}};
g.metadata_merge_strategy = "REPLACE";
invalid([&] { g.validate(); });
g.metadata_merge_strategy.clear();
g.allowed_topics = {Topic::managed("lowercase")};
invalid([&] { g.validate(); });
}
TEST(memory_bodies, retrieve_modes) {
RetrieveRequest r;
r.scope = {{"user_id", "1"}};
r.validate();
ASSERT_TRUE(r.to_json().find("similaritySearchParams") == nullptr);
ASSERT_TRUE(r.to_json().find("simpleRetrievalParams") == nullptr);
r.page_size = 10;
r.page_token = "tok";
r.validate();
Json simple = r.to_json();
keys_declared(simple, Call::kMemoryRetrieve);
ASSERT_EQ(simple.find("simpleRetrievalParams")->find("pageSize")->as_int(), 10);
RetrieveRequest s;
s.scope = {{"user_id", "1"}};
s.search_query = "tea";
s.filter = "topics=\"x\"";
s.memory_types = {"STRUCTURED_PROFILE"};
s.filter_groups = {{{"src", MetadataFilter::Op::kEqual, false, MetadataValue::of_string("chat")}}};
s.validate();
Json sim = s.to_json();
keys_declared(sim, Call::kMemoryRetrieve);
ASSERT_EQ(sim.find("similaritySearchParams")->find("topK")->as_int(), MemoryCaps::kDefaultTopK);
ASSERT_EQ(sim.find("filterGroups")->as_array()[0].find("filters")->as_array()[0].find("op")->as_string(),
std::string("EQUAL"));
s.top_k = 51;
invalid([&] { s.validate(); });
s.top_k = 5;
s.page_size = 5;
invalid([&] { s.validate(); }); // page size is not a similarity knob
s.page_size = 0;
s.search_query.clear();
invalid([&] { s.validate(); }); // top_k without a query
s.top_k = 0;
s.memory_types = {"BOGUS"};
invalid([&] { s.validate(); });
s.memory_types.clear();
s.search_query = std::string(1001, 'a');
invalid([&] { s.validate(); });
RetrieveRequest none;
invalid([&] { none.validate(); }); // scope required
}
TEST(memory_bodies, create_patch_ingest) {
MemorySpec m;
m.memory_id = "mem-1";
m.fact = "likes tea";
m.scope = {{"user_id", "1"}};
m.topics = {Topic::managed("USER_PREFERENCES")};
m.ttl = "3600s";
m.metadata["k"] = MetadataValue::of_bool(true);
m.metadata["t"] = MetadataValue::of_timestamp("2025-01-31T11:30:00Z");
m.context = "ctx";
m.revision.disable = true;
m.validate();
keys_declared(m.to_json(), Call::kMemoryCreate);
m.fact.clear();
invalid([&] { m.validate(); }); // fact or structured content
m.structured_content = Json::object();
invalid([&] { m.validate(); }); // needs schemaId and data
Json sc = Json::object();
sc.set("schemaId", Json("user-profile"));
sc.set("data", Json::object());
m.structured_content = sc;
m.memory_type = "STRUCTURED_PROFILE";
m.validate();
keys_declared(m.to_json(), Call::kMemoryCreate);
m.memory_type = "OTHER";
invalid([&] { m.validate(); });
m.memory_type.clear();
m.memory_id = "1bad";
invalid([&] { m.validate(); });
m.memory_id = "ok";
m.fact = std::string(4001, 'x');
invalid([&] { m.validate(); });
MemoryPatch p;
p.memory_id = "mem-1";
p.fact = "likes coffee";
p.update_mask = "fact";
p.validate();
keys_declared(p.to_json(), Call::kMemoryPatch);
p.update_mask.clear();
invalid([&] { p.validate(); });
IngestRequest in;
in.scope = {{"user_id", "1"}};
invalid([&] { in.validate(); }); // no events
in.events.push_back({"e1", "2025-01-31T11:30:00Z", Content::user("hi")});
in.stream_id = "s1";
in.trigger_event_count = 10;
in.trigger_idle_duration = "600s";
in.force_flush = true;
in.validate();
Json ib = in.to_json();
keys_declared(ib, Call::kMemoryIngestEvents);
ASSERT_EQ(ib.find("generationTriggerConfig")->find("generationRule")->find("eventCount")->as_int(), 10);
in.trigger_fixed_interval = "30s"; // Google: minute granularity at least
invalid([&] { in.validate(); });
in.trigger_fixed_interval.clear();
in.events[0].event_time = "soon";
invalid([&] { in.validate(); });
}
TEST(memory_bodies, topics_metadata_filters) {
ASSERT_EQ(Topic::managed("USER_PERSONAL_INFO").to_json().dump(),
std::string("{\"managedMemoryTopic\":\"USER_PERSONAL_INFO\"}"));
ASSERT_EQ(Topic::custom("x").to_json().dump(), std::string("{\"customMemoryTopicLabel\":\"x\"}"));
ASSERT_EQ(Topic::from_json(Topic::custom("y").to_json()).value, std::string("y"));
ASSERT_EQ(MetadataValue::of_double(2).to_json().dump(), std::string("{\"doubleValue\":2}"));
FilterGroups groups = {{{"a", MetadataFilter::Op::kGreaterThan, true, MetadataValue::of_double(1)}}};
check_filter_groups(groups);
Json gj = filter_groups_json(groups);
const Json& f = gj.as_array()[0].find("filters")->as_array()[0];
ASSERT_EQ(f.find("op")->as_string(), std::string("GREATER_THAN"));
ASSERT_TRUE(f.find("negate")->as_bool());
FilterGroups empty_group(1);
invalid([&] { check_filter_groups(empty_group); });
FilterGroups too_many(11, groups[0]);
invalid([&] { check_filter_groups(too_many); });
Memory mem = Memory::from_json(Json::parse(
"{\"name\":\"x/memories/m1\",\"fact\":\"f\",\"scope\":{\"u\":\"1\"},"
"\"topics\":[{\"managedMemoryTopic\":\"USER_PREFERENCES\"}]}"));
ASSERT_EQ(mem.id(), std::string("m1"));
ASSERT_EQ(mem.topics[0].value, std::string("USER_PREFERENCES"));
ASSERT_EQ(mem.scope.at("u"), std::string("1"));
}
TEST(sessions_service, validation_runs_before_any_traffic) {
Rig rig;
Sessions s(rig.client, EngineName(kEngine));
MemoryBank b(rig.client, EngineName(kEngine));
invalid([&] { s.get("BAD ID"); });
invalid([&] { s.delete_session(""); });
invalid([&] { s.create(SessionSpec{}); });
invalid([&] { s.list({"a\nb", "", 0}); });
invalid([&] { s.list({"", "", 101}); });
invalid([&] { s.list_events("x/y"); });
invalid([&] { s.compact("s1", CompactRequest{}); });
invalid([&] { s.append_event("s1", SessionEvent{}); });
invalid([&] { b.get("1bad"); });
invalid([&] { b.delete_memory("Bad"); });
invalid([&] { b.retrieve(RetrieveRequest{}); });
invalid([&] { b.retrieve_profiles({}); });
invalid([&] { b.get_revision("m1", "a/b"); });
invalid([&] { b.rollback("m1", ".."); });
invalid([&] { b.list({"", "\t", 0}); });
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
}
TEST(sessions_service, purge_is_guarded) {
Rig rig;
MemoryBank b(rig.client, EngineName(kEngine));
PurgeRequest empty;
invalid([&] { b.purge(empty); }); // a filter is required
PurgeRequest forced;
forced.filter = "scope.user_id=\"1\"";
forced.force = true;
invalid([&] { b.purge(forced); }); // no confirm
forced.confirm = "wrong";
invalid([&] { b.purge(forced); }); // confirm must be the engine id
ASSERT_FALSE(PurgeRequest{}.force); // dry run is the default
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
}
TEST(sessions_service, operation_names_are_confined_to_the_engine) {
Rig rig;
Sessions s(rig.client, EngineName(kEngine));
for (const char* bad : {"", "operations/1", "projects/p1/locations/us-central1/reasoningEngines/other/operations/1",
"projects/p1/locations/us-central1/reasoningEngines/e1/sessions/s",
"projects/p1/locations/us-central1/reasoningEngines/e1/operations/../x",
"projects/p1/locations/us-central1/reasoningEngines/e1/operations/1?x=1"}) {
invalid([&] { s.operation(bad); });
invalid([&] { s.cancel_operation(bad); });
invalid([&] { s.wait(bad); });
}
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
}
TEST(sessions_service, no_credential_is_loud_and_offline) {
Rig rig(false);
Sessions s(rig.client, EngineName(kEngine));
MemoryBank b(rig.client, EngineName(kEngine));
ASSERT_FALSE(s.configured());
ASSERT_THROW(s.get("s1"), NotConfiguredError);
ASSERT_THROW(s.list(), NotConfiguredError);
ASSERT_THROW(b.get("m1"), NotConfiguredError);
ASSERT_THROW(b.list(), NotConfiguredError);
MemorySpec m;
m.fact = "f";
m.scope = {{"u", "1"}};
ASSERT_THROW(b.create(m), NotConfiguredError);
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
}
TEST(sessions_service, endpoint_follows_the_engine_location) {
Rig rig;
Sessions s(rig.client, EngineName(kEngine));
ASSERT_EQ(s.endpoint().base_url,
std::string("https://us-central1-aiplatform.googleapis.com/v1beta1"));
MemoryBank b(rig.client, EngineName("projects/p1/locations/europe-west4/reasoningEngines/e2"));
ASSERT_EQ(b.endpoint().base_url,
std::string("https://europe-west4-aiplatform.googleapis.com/v1beta1"));
ASSERT_EQ(std::string(kDiscoveryVersion), std::string("v1beta1"));
}
// Read-only probe against the real service. Creates nothing. An express API
// key (AQ.) is accepted on v1beta1 and a missing engine answers 404; a
// project OAuth token (GOOGLE_ACCESS_TOKEN) does the same. Needs
// MOLO_LIVE_NET=1, a credential and GOOGLE_CLOUD_PROJECT (read from env,
// never printed).
TEST(sessions_live, reads_under_a_missing_engine_answer_not_found) {
std::string project = Credentials::env("GOOGLE_CLOUD_PROJECT");
bool has_credential = !Credentials::env().empty() || !Credentials::env("GOOGLE_ACCESS_TOKEN").empty();
if (!std::getenv("MOLO_LIVE_NET") || !has_credential || project.empty()) {
std::cout << "SKIP sessions_live (set MOLO_LIVE_NET=1, GOOGLE_API_KEY or "
"GOOGLE_ACCESS_TOKEN, and GOOGLE_CLOUD_PROJECT)\n";
return;
}
auto client = GoogleClient::from_env();
EngineName engine("projects/" + project +
"/locations/us-central1/reasoningEngines/1");
Sessions s(client, engine);
MemoryBank b(client, engine);
auto expect_not_found = [](const std::function<void()>& fn) {
try {
fn();
} catch (const GoogleError& e) {
ASSERT_EQ(e.http_status(), 404);
ASSERT_EQ(e.status(), std::string("NOT_FOUND"));
return;
}
FAIL("a missing engine must answer NOT_FOUND");
};
expect_not_found([&] { s.list(); });
expect_not_found([&] { s.get("probe"); });
expect_not_found([&] { s.list_events("probe"); });
expect_not_found([&] { b.list(); });
expect_not_found([&] { b.get("probe"); });
expect_not_found([&] { b.list_revisions("probe"); });
}