feat(clients): sessions: Agent Sessions and Memory Bank, discovery-checked call table, guarded purge, live read probes

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 04:36:42 +02:00
co-authored by Claude Sonnet 5.5
parent 6d744a433f
commit 6c0e969db0
20 changed files with 3242 additions and 3 deletions
+350 -3
View File
@@ -1,13 +1,360 @@
#include "../AgentDemos.hpp"
#include <memory>
#include "../../fw/Router.hpp"
#include "../../fw/Templates.hpp"
#include "../../fw/Validate.hpp"
#include "google/resource.h"
#include "google/sessions/caps.h"
#include "google/sessions/calls.h"
#include "google/sessions/memory_bank.h"
#include "google/sessions/sessions.h"
namespace molo::example::app {
// Agent Platform: sessions. Stub: the module agent fills this in.
// Agent Platform: Agent Sessions and Agent Memory Bank over src/google/sessions.
// Every route that would call Google is a POST (or DELETE) and answers 503
// google_not_configured without a credential and 422 on bad input. The engine
// is a full reasoningEngines name or a bare engine id (project from
// GOOGLE_CLOUD_PROJECT). Live behavior needs an Agent Engine resource and a
// credential Google accepts for it; see src/google/sessions/SPEC.md.
namespace {
namespace gs = molo::google::sessions;
using Flat = std::map<std::string, std::string>;
using GJson = molo::clients::body::Json;
const char kSessionsPage[] = R"SESSIONS({% extends "base.html" %}
{% block content %}
<h1>Agent sessions and memory</h1>
<p>Sessions and Memory Bank under one Agent Engine
(<code>projects/P/locations/L/reasoningEngines/E</code>, or a bare engine id).
Every call below is a JSON POST (or DELETE) and answers 503
<code>google_not_configured</code> without a credential.</p>
<p><a href="/agent/sessions/status">Status</a></p>
<div style="overflow-x:auto">
<table>
<thead><tr><th>Route</th><th>Body</th></tr></thead>
<tbody>
<tr><td>POST /agent/sessions/create</td><td>engine, user_id, session_id?, display_name?, ttl?</td></tr>
<tr><td>POST /agent/sessions/get</td><td>engine, session_id</td></tr>
<tr><td>POST /agent/sessions/list</td><td>engine, filter?</td></tr>
<tr><td>DELETE /agent/sessions/session</td><td>query: engine, id</td></tr>
<tr><td>POST /agent/sessions/events/append</td><td>engine, session_id, author, invocation_id, timestamp, text</td></tr>
<tr><td>POST /agent/sessions/events/list</td><td>engine, session_id</td></tr>
<tr><td>POST /agent/sessions/memories/generate</td><td>engine, scope_key, scope_value, text or session_id</td></tr>
<tr><td>POST /agent/sessions/memories/retrieve</td><td>engine, scope_key, scope_value, query?, top_k?</td></tr>
<tr><td>POST /agent/sessions/memories/create</td><td>engine, scope_key, scope_value, fact, memory_id?</td></tr>
<tr><td>POST /agent/sessions/memories/get</td><td>engine, memory_id</td></tr>
<tr><td>POST /agent/sessions/memories/list</td><td>engine, filter?</td></tr>
<tr><td>DELETE /agent/sessions/memories/memory</td><td>query: engine, id</td></tr>
<tr><td>POST /agent/sessions/memories/profiles</td><td>engine, scope_key, scope_value</td></tr>
<tr><td>POST /agent/sessions/memories/purge</td><td>engine, filter, force?, confirm? (dry run by default)</td></tr>
</tbody>
</table>
</div>
{% endblock %}
)SESSIONS";
[[noreturn]] void rethrow(const google::GoogleError& e) {
if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED")
throw fw::HttpError(503, "google_not_configured", e.message());
if (e.service().empty() && e.status() == "INVALID_ARGUMENT")
throw fw::HttpError(422, "validation_error", e.message());
throw fw::HttpError(502, "google_error", e.status() + ": " + e.message());
}
template <typename F>
auto guarded(F&& f) -> decltype(f()) {
try {
return f();
} catch (const google::GoogleError& e) {
rethrow(e);
}
}
std::string field(const Flat& in, const std::string& key) {
auto it = in.find(key);
return it == in.end() ? "" : it->second;
}
fw::Response answer(const GJson& body, int status = 200) {
fw::Response res = fw::JsonResponse(body.dump(), status);
res.headers.set("Cache-Control", "no-store");
return res;
}
// Routes for one demo: resolves the engine and runs the typed services.
class SessionsRoutes {
public:
explicit SessionsRoutes(std::shared_ptr<google::GoogleClient> client)
: client_(std::move(client)) {}
bool configured() const { return client_->configured(); }
gs::EngineName engine_of(const std::string& value) const {
if (value.rfind("projects/", 0) == 0) return gs::EngineName(value);
google::CloudContext ctx = google::CloudContext::from_env();
return gs::EngineName(ctx.child("reasoningEngines", value));
}
gs::Sessions sessions(const std::string& engine) const {
return gs::Sessions(client_, engine_of(engine));
}
gs::MemoryBank bank(const std::string& engine) const {
return gs::MemoryBank(client_, engine_of(engine));
}
static gs::StringMap scope_of(const Flat& in) {
gs::StringMap scope;
if (!field(in, "scope_key").empty() || !field(in, "scope_value").empty())
scope[field(in, "scope_key")] = field(in, "scope_value");
return scope;
}
private:
std::shared_ptr<google::GoogleClient> client_;
};
GJson memory_json(const gs::Memory& m) { return m.to_json(); }
} // namespace
void register_agent_sessions_demo(fw::Router& router, Services& services) {
(void)router;
(void)services;
if (!services.google) services.google = google::GoogleClient::from_env();
auto routes = std::make_shared<SessionsRoutes>(services.google);
fw::Environment* env = services.templates.get();
env->add_template("agent_sessions.html", kSessionsPage);
services.add_feature("agent sessions", "/agent/sessions");
router.get("/agent/sessions", "agent-sessions-page", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("Agent sessions");
return fw::Response(200, env->render("agent_sessions.html", ctx),
"text/html; charset=utf-8");
});
router.get("/agent/sessions/status", "agent-sessions-status", [routes](fw::Request req) {
(void)req;
GJson out = GJson::object();
out.set("configured", GJson(routes->configured()));
out.set("surface", GJson(std::string(gs::kDiscoveryService) + " " + gs::kDiscoveryVersion));
out.set("calls", GJson(static_cast<int>(gs::Call::kCount)));
GJson caps = GJson::object();
caps.set("max_session_id_chars", GJson(static_cast<int>(gs::SessionsCaps::kMaxIdChars)));
caps.set("max_list_items", GJson(static_cast<int>(gs::SessionsCaps::kMaxListItems)));
caps.set("max_top_k", GJson(gs::MemoryCaps::kMaxTopK));
caps.set("max_fact_chars", GJson(static_cast<int>(gs::MemoryCaps::kMaxFactChars)));
out.set("caps", caps);
return answer(out);
});
// Sessions ---------------------------------------------------------------
router.post("/agent/sessions/create", "agent-sessions-create", [routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::SessionSpec spec;
spec.session_id = field(in, "session_id");
spec.user_id = field(in, "user_id");
spec.display_name = field(in, "display_name");
spec.ttl = field(in, "ttl");
return answer(routes->sessions(field(in, "engine")).create(spec).to_json(), 201);
});
});
router.post("/agent/sessions/get", "agent-sessions-get", [routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
return answer(routes->sessions(field(in, "engine")).get(field(in, "session_id")).to_json());
});
});
router.post("/agent/sessions/list", "agent-sessions-list", [routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::SessionListOptions options;
options.filter = field(in, "filter");
GJson arr = GJson::array();
for (const gs::Session& s : routes->sessions(field(in, "engine")).list(options))
arr.push(s.to_json());
GJson out = GJson::object();
out.set("sessions", arr);
return answer(out);
});
});
router.del("/agent/sessions/session", "agent-sessions-delete", [routes](fw::Request req) {
return guarded([&] {
routes->sessions(req.query_or("engine", "")).delete_session(req.query_or("id", ""));
GJson out = GJson::object();
out.set("deleted", GJson(true));
return answer(out);
});
});
router.post("/agent/sessions/events/append", "agent-sessions-event-append",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::SessionEvent ev;
ev.author = field(in, "author");
ev.invocation_id = field(in, "invocation_id");
ev.timestamp = field(in, "timestamp");
if (!field(in, "text").empty()) {
std::string role = field(in, "role").empty() ? "user" : field(in, "role");
google::Content c = role == "model" ? google::Content::model(field(in, "text"))
: google::Content::user(field(in, "text"));
ev.content = c;
}
routes->sessions(field(in, "engine")).append_event(field(in, "session_id"), ev);
GJson out = GJson::object();
out.set("appended", GJson(true));
return answer(out);
});
});
router.post("/agent/sessions/events/list", "agent-sessions-event-list",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
GJson arr = GJson::array();
for (const gs::SessionEvent& e :
routes->sessions(field(in, "engine")).list_events(field(in, "session_id")))
arr.push(e.to_json());
GJson out = GJson::object();
out.set("events", arr);
return answer(out);
});
});
// Memory Bank ------------------------------------------------------------
router.post("/agent/sessions/memories/generate", "agent-memories-generate",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::MemoryGenerateRequest g;
g.scope = SessionsRoutes::scope_of(in);
if (!field(in, "session_id").empty()) {
g.source = gs::MemoryGenerateRequest::Source::kSession;
g.session_id = field(in, "session_id");
} else {
g.source = gs::MemoryGenerateRequest::Source::kContents;
if (!field(in, "text").empty()) g.contents.push_back(google::Content::user(field(in, "text")));
}
GJson arr = GJson::array();
for (const gs::GeneratedMemory& m : routes->bank(field(in, "engine")).generate(g)) {
GJson item = GJson::object();
item.set("memory", memory_json(m.memory));
item.set("action", GJson(m.action));
arr.push(item);
}
GJson out = GJson::object();
out.set("generated", arr);
return answer(out);
});
});
router.post("/agent/sessions/memories/retrieve", "agent-memories-retrieve",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::RetrieveRequest r;
r.scope = SessionsRoutes::scope_of(in);
r.search_query = field(in, "query");
if (!field(in, "top_k").empty()) r.top_k = std::atoi(field(in, "top_k").c_str());
gs::RetrieveResult res = routes->bank(field(in, "engine")).retrieve(r);
GJson arr = GJson::array();
for (const gs::RetrievedMemory& m : res.memories) {
GJson item = GJson::object();
item.set("memory", memory_json(m.memory));
if (m.has_distance) item.set("distance", GJson(m.distance));
arr.push(item);
}
GJson out = GJson::object();
out.set("memories", arr);
out.set("next_page_token", GJson(res.next_page_token));
return answer(out);
});
});
router.post("/agent/sessions/memories/create", "agent-memories-create",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::MemorySpec spec;
spec.memory_id = field(in, "memory_id");
spec.fact = field(in, "fact");
spec.scope = SessionsRoutes::scope_of(in);
return answer(memory_json(routes->bank(field(in, "engine")).create(spec)), 201);
});
});
router.post("/agent/sessions/memories/get", "agent-memories-get", [routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
return answer(memory_json(routes->bank(field(in, "engine")).get(field(in, "memory_id"))));
});
});
router.post("/agent/sessions/memories/list", "agent-memories-list", [routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::MemoryListOptions options;
options.filter = field(in, "filter");
GJson arr = GJson::array();
for (const gs::Memory& m : routes->bank(field(in, "engine")).list(options))
arr.push(memory_json(m));
GJson out = GJson::object();
out.set("memories", arr);
return answer(out);
});
});
router.del("/agent/sessions/memories/memory", "agent-memories-delete",
[routes](fw::Request req) {
return guarded([&] {
routes->bank(req.query_or("engine", "")).delete_memory(req.query_or("id", ""));
GJson out = GJson::object();
out.set("deleted", GJson(true));
return answer(out);
});
});
router.post("/agent/sessions/memories/profiles", "agent-memories-profiles",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
GJson profiles = GJson::object();
for (const auto& [id, p] :
routes->bank(field(in, "engine")).retrieve_profiles(SessionsRoutes::scope_of(in)))
profiles.set(id, p.fields);
GJson out = GJson::object();
out.set("profiles", profiles);
return answer(out);
});
});
// Irreversible when force is true: needs confirm == engine id.
router.post("/agent/sessions/memories/purge", "agent-memories-purge",
[routes](fw::Request req) {
Flat in = fw::parse_json_object_flat(req.body);
return guarded([&] {
gs::PurgeRequest p;
p.filter = field(in, "filter");
p.force = field(in, "force") == "true";
p.confirm = field(in, "confirm");
gs::PurgeResult r = routes->bank(field(in, "engine")).purge(p);
GJson out = GJson::object();
out.set("forced", GJson(r.forced));
out.set("purge_count", GJson(static_cast<int>(r.purge_count)));
return answer(out);
});
});
}
} // namespace molo::example::app