melchizedek-agents 0.9.0

package/dist/lib/session/supabaseSessionService.js

@@ -0,0 +1,193 @@
+import { BaseSessionService, createSession } from '@google/adk';
+import { randomUUID } from 'crypto';
+import { trimEventForStorage } from "./transcript.js";
+export class SupabaseSessionService extends BaseSessionService {
+    supabase;
+    constructor(supabaseClient) {
+        super();
+        this.supabase = supabaseClient;
+    }
+    getDbId(request) {
+        return `${request.appName}:${request.userId}:${request.sessionId}`;
+    }
+    async createSession(request) {
+        const sessionId = request.sessionId || randomUUID();
+        const dbId = this.getDbId({ appName: request.appName, userId: request.userId, sessionId });
+        const session = createSession({
+            id: sessionId,
+            appName: request.appName,
+            userId: request.userId,
+            state: request.state || {},
+            events: [],
+            lastUpdateTime: Date.now()
+        });
+        const cleanSession = JSON.parse(JSON.stringify(session));
+        const expireAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
+        const { error } = await this.supabase
+            .from('adk_sessions')
+            .upsert({
+            id: dbId,
+            app_name: cleanSession.appName,
+            user_id: cleanSession.userId,
+            state: cleanSession.state,
+            events: cleanSession.events,
+            last_update_time: cleanSession.lastUpdateTime,
+            expire_at: expireAt
+        });
+        if (error) {
+            console.error('Error creating session in Supabase:', error);
+            throw new Error(`Failed to create session: ${error.message}`);
+        }
+        return session;
+    }
+    async getSession(request) {
+        const dbId = this.getDbId(request);
+        const { data, error } = await this.supabase
+            .from('adk_sessions')
+            .select('*')
+            .eq('id', dbId)
+            .single();
+        if (error) {
+            if (error.code === 'PGRST116') {
+                return undefined; // Not found
+            }
+            console.error('Error getting session from Supabase:', error);
+            throw new Error(`Failed to get session: ${error.message}`);
+        }
+        if (!data)
+            return undefined;
+        const session = {
+            id: request.sessionId,
+            appName: data.app_name,
+            userId: data.user_id,
+            state: data.state || {},
+            events: data.events || [],
+            lastUpdateTime: data.last_update_time
+        };
+        // Handle GetSessionConfig (numRecentEvents, afterTimestamp) filters
+        if (request.config) {
+            if (request.config.afterTimestamp) {
+                session.events = session.events.filter((e) => e.timestamp && e.timestamp > request.config.afterTimestamp);
+            }
+            if (request.config.numRecentEvents) {
+                session.events = session.events.slice(-request.config.numRecentEvents);
+            }
+        }
+        return session;
+    }
+    /**
+     * ADK's ListSessions contract carries paging: `limit` with either `page`
+     * (1-based, wins) or `offset` (0-based), plus an optional sort by last
+     * update, and the response must report where in the set the caller is.
+     * The window is pushed down to Postgres via .range(), and `count:
+     * 'exact'` returns the TOTAL matching rows alongside the page — so
+     * totalItems is the real total, not the slice length. With no `limit`,
+     * the whole set is one page, which is what the ADK's own docs specify
+     * ("Page size used. Equals `totalItems` when no limit was requested").
+     */
+    async listSessions(request) {
+        const { limit, order } = request;
+        const offset = limit !== undefined && request.page !== undefined
+            ? (Math.max(1, request.page) - 1) * limit
+            : (request.offset ?? 0);
+        let query = this.supabase
+            .from('adk_sessions')
+            .select('id, app_name, user_id, state, last_update_time', { count: 'exact' })
+            .eq('app_name', request.appName)
+            .eq('user_id', request.userId);
+        if (order) {
+            query = query.order('last_update_time', { ascending: order === 'asc' });
+        }
+        if (limit !== undefined) {
+            query = query.range(offset, offset + limit - 1);
+        }
+        else if (offset > 0) {
+            // An offset without a limit still means "skip these".
+            query = query.range(offset, offset + 999_999);
+        }
+        const { data, error, count } = await query;
+        if (error) {
+            console.error('Error listing sessions from Supabase:', error);
+            throw new Error(`Failed to list sessions: ${error.message}`);
+        }
+        const sessions = (data || []).map(row => {
+            // Extract the original sessionId from the composite key if possible
+            const parts = row.id.split(':');
+            const originalSessionId = parts.length >= 3 ? parts.slice(2).join(':') : row.id;
+            return {
+                id: originalSessionId,
+                appName: row.app_name,
+                userId: row.user_id,
+                state: row.state || {},
+                events: [], // ListSessions usually returns omitted events to save bandwidth
+                lastUpdateTime: row.last_update_time
+            };
+        });
+        const totalItems = count ?? sessions.length;
+        const pageSize = limit ?? totalItems;
+        return {
+            sessions,
+            page: limit ? Math.floor(offset / limit) + 1 : 1,
+            limit: pageSize,
+            totalItems,
+            totalPages: limit ? Math.max(1, Math.ceil(totalItems / limit)) : 1,
+        };
+    }
+    async deleteSession(request) {
+        const dbId = this.getDbId(request);
+        const { error } = await this.supabase
+            .from('adk_sessions')
+            .delete()
+            .eq('id', dbId);
+        if (error) {
+            console.error('Error deleting session from Supabase:', error);
+            throw new Error(`Failed to delete session: ${error.message}`);
+        }
+    }
+    async appendEvent(request) {
+        const { session, event } = request;
+        const dbId = this.getDbId({ appName: session.appName, userId: session.userId, sessionId: session.id });
+        // Partial events are streaming fragments of an event that is appended
+        // whole when it completes. The runner already guards this, but the
+        // base contract does too, and a service that persists them would write
+        // every token twice.
+        if (event.partial)
+            return event;
+        // Standard ADK internal state merging. This MUST go through the base
+        // implementation: it applies `event.actions.stateDelta` to
+        // `session.state` and strips `temp:` keys before pushing the event.
+        // Re-implementing it as a bare `events.push` (as this did until
+        // 2026-08-15) silently drops every state write — `output_key`, any
+        // state-injected instruction variable — and leaves `session.state`
+        // permanently `{}`, which is exactly what every stored row showed.
+        await super.appendEvent({ session, event });
+        session.lastUpdateTime = Date.now();
+        // Trim on the SERIALIZED COPY only. The live session keeps thought
+        // signatures and real tool payloads — the agent's own tool loop reads
+        // them back mid-turn — but nothing reads them from the ROW: the
+        // projection drops both on the way into a prompt, and the memory
+        // service walks `part.text` alone. Across 128 live sessions they were
+        // ~90% of every byte stored (73% of it Gemini's `thoughtSignature`),
+        // and this method re-uploads the whole array on every event, so those
+        // bytes were paid for again on each one. See trimEventForStorage.
+        const cleanSession = JSON.parse(JSON.stringify(session));
+        cleanSession.events = cleanSession.events.map((e) => trimEventForStorage(e));
+        const expireAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
+        const { error } = await this.supabase
+            .from('adk_sessions')
+            .upsert({
+            id: dbId,
+            app_name: cleanSession.appName,
+            user_id: cleanSession.userId,
+            state: cleanSession.state,
+            events: cleanSession.events,
+            last_update_time: cleanSession.lastUpdateTime,
+            expire_at: expireAt
+        });
+        if (error) {
+            console.error('Error appending event to session in Supabase:', error);
+            throw new Error(`Failed to append event: ${error.message}`);
+        }
+        return event;
+    }
+}

package/dist/lib/session/transcript.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Cross-agent transcript sharing.
+ *
+ * ── The problem this solves ───────────────────────────────────────────────
+ * Under plan-dispatch every route runs as its OWN root agent (XScout,
+ * Conversationalist, FinancialAnalyst) against ONE shared session. Sharing
+ * the session is necessary but not sufficient: ADK decides how a stored
+ * event is rendered into a prompt by comparing `event.author` against the
+ * agent that is running, and every prior event fails that comparison the
+ * moment the route changes. `convertForeignEvent` then rewrites each one to
+ * `role: "user"` prefixed with "For context:".
+ *
+ * Replaying a real production session — a four-turn thread that had passed
+ * through three routes — through ADK's own content processor showed what the
+ * last route actually received: 15 contents, 118,013 bytes, and EVERY ONE of them
+ * `role: "user"`. Not a single `role: "model"` turn in the prompt. The
+ * history was all there — and unreadable as a conversation, because nothing
+ * in it was marked as having been said by the desk. That is the "it doesn't
+ * know what I'm referring to" failure, and no amount of session sharing
+ * fixes it, because sharing was never the broken part.
+ *
+ * Two further leaks rode along in the same conversion. `convertForeignEvent`
+ * clones any part it does not recognise verbatim, so the previous route's
+ * private chain-of-thought ("**My Micron Monday Decision Strategy** Okay, so
+ * the question is…", `thought: true`) arrived as USER speech. And raw tool
+ * payloads were inlined as text — one `load_memory` result alone was 23,502
+ * characters, one `get_company_fundamentals` 8,953 — all of it handed to a
+ * 400-character, tool-less flash-lite route that could do nothing with it.
+ *
+ * ── The fix ───────────────────────────────────────────────────────────────
+ * Project the stored transcript before ADK ever sees it: rewrite each past
+ * agent turn to the CURRENT agent's name so it survives as a real
+ * `role: "model"` turn, label it with the desk that spoke, and drop what no
+ * successor can use — thoughts, tool calls, tool results.
+ *
+ * The projection is a READ-TIME view. The stored session keeps everything,
+ * verbatim, because long-term memory ingestion reads the real record.
+ */
+import { BaseSessionService } from '@google/adk';
+import type { CreateSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse, DeleteSessionRequest, Session, Event } from '@google/adk';
+/** Tuning for {@link projectTranscript}. Defaults are the production values. */
+export interface ProjectionOptions {
+    /**
+     * Character budget for the projected HISTORY, walked backwards from the
+     * newest event. Older events are dropped whole once it is exhausted.
+     *
+     * A bound is required — the session row is a 7-day append-only log and a
+     * busy channel reaches six figures of text — but it is set generously:
+     * 40,000 characters of tool-free, thought-free prose is many turns, and
+     * the analyst route recovers older material through long-term memory.
+     */
+    maxHistoryChars?: number;
+    /**
+     * Ceiling on the NUMBER of past turns kept, whichever binds first with
+     * `maxHistoryChars`.
+     *
+     * A character budget alone is not a bound on prompt shape: a thread of
+     * short exchanges fits 43 turns inside 40,000 characters, and a model
+     * reading 43 turns of history to answer one question is paying attention
+     * tax no budget in bytes describes. Turns and bytes are different costs;
+     * both need a ceiling.
+     */
+    maxHistoryTurns?: number;
+    /** Longest single past turn kept intact; the tail is elided. */
+    maxTurnChars?: number;
+}
+/**
+ * Longest tool result kept in the DURABLE record. See {@link trimEventForStorage}.
+ */
+export declare const DEFAULT_MAX_STORED_PAYLOAD_CHARS = 2000;
+/**
+ * Render a stored transcript as history the given agent can read.
+ *
+ * User events pass through untouched. Every agent event becomes a
+ * `role: "model"` turn ATTRIBUTED to `forAgent`, which is what keeps ADK
+ * from rewriting it into "For context:" user text — with the original
+ * author kept as a visible `[Name]` label when it was a different desk, so
+ * attribution survives without costing the turn structure.
+ *
+ * Events that said nothing out loud (a pure tool call, a pure tool result)
+ * disappear entirely. Calls and their responses are dropped together, so
+ * ADK's function-response pairing never sees a widowed half.
+ *
+ * Pure and synchronous — see tests/transcript.test.ts.
+ */
+export declare function projectTranscript(events: Event[], forAgent: string, options?: ProjectionOptions): Event[];
+/**
+ * Strip from an event what no reader of the STORED session will ever use.
+ *
+ * ── What the durable record is actually made of ───────────────────────────
+ * Measured across 128 live sessions, by part field:
+ *
+ *     thoughtSignature            14.14 MB   73.3%
+ *     functionResponse.response    2.07 MB   10.8%
+ *     text (the conversation)      1.86 MB    9.6%
+ *     toolResponse.response        1.06 MB    5.5%
+ *
+ * Nine-tenths of every byte stored is machinery. `thoughtSignature` is the
+ * opaque base64 blob Gemini attaches for thought continuity — a single part
+ * of it reached 115 KB — and tool payloads are the rest, the largest being
+ * Gemini's grounding `search_suggestions`, an HTML and CSS widget attached
+ * to every web-search result.
+ *
+ * Beware the shape of this data when measuring it: bucketing a part by
+ * whichever tool key it carries attributes the whole part to the tool
+ * response, when the weight is in a sibling field. That misattribution said
+ * "76% is tool results" and predicted a 70% saving from eliding payloads
+ * alone; the real saving from that change was 12%.
+ *
+ * ── Why none of it is needed ──────────────────────────────────────────────
+ * The stored row has exactly two readers. {@link projectTranscript} drops
+ * thought parts and tool traffic entirely on the way into a prompt, so a
+ * stored signature is never replayed to a model. The memory service's
+ * `serializeEvents` walks `part.text` alone, so a payload has never
+ * contributed one extracted fact. Everything above is written, re-uploaded
+ * on every later event in the turn (this service re-upserts the whole
+ * array), and re-fetched whole next turn — for nothing. One live session had
+ * reached 1.17 MB; a 60-turn conversation uploaded ~288 MB getting there.
+ *
+ * ── What survives ─────────────────────────────────────────────────────────
+ * A trimmed response KEEPS its shape: `id` and `name` are preserved and only
+ * the body is replaced, because ADK pairs calls to responses by id
+ * (`rearrangeEventsForLatestFunctionResponse` throws on a widowed half), so
+ * an elided result must remain a result. The marker records what was dropped
+ * and how big it was — what an operator reading the row needs. Small results
+ * pass through untouched: they are cheap, and a short one is occasionally
+ * the only record of what a number was.
+ *
+ * ── The one constraint on changing this ───────────────────────────────────
+ * Dropping `thoughtSignature` is safe BECAUSE the projection never feeds
+ * stored events back to a model. Anything that starts replaying raw stored
+ * events into Gemini would need the signature preserved, or lose thought
+ * continuity across a resumed session.
+ *
+ * Pure: returns a new event, never mutates the input. The caller applies it
+ * to the SERIALIZED COPY only — the live in-memory session must keep both
+ * signature and payloads, or the agent's own tool loop breaks mid-turn.
+ */
+export declare function trimEventForStorage(event: Event, maxPayloadChars?: number): Event;
+/**
+ * A compact plain-text digest of the exchange, for an agent that must be
+ * given history as INPUT rather than as conversation.
+ *
+ * The dispatch classifier is that agent. It runs in its own lane so its JSON
+ * verdicts never pollute the user-facing transcript — and the cost of that
+ * isolation, in production, was a router that had never seen a single answer
+ * it routed. On 2026-08-15 its lane held four user messages and four of its
+ * own verdicts, nothing else; a user's counter-argument to the desk's
+ * MU/SNDK/NVDA/AMD call therefore read as a remark with no request behind
+ * it, and went to small talk. Its own rules ("follow-ups on prior analysis →
+ * FinancialAnalyst") were unusable, because no prior analysis was in view.
+ *
+ * @param maxTurns        newest N exchanges to show
+ * @param maxCharsPerTurn per-line budget — the router classifies, it does not
+ *                        read; the shape of an answer is enough
+ */
+export declare function renderTranscriptDigest(events: Event[], { maxTurns, maxCharsPerTurn }?: {
+    maxTurns?: number;
+    maxCharsPerTurn?: number;
+}): string;
+/**
+ * A read-time projection over another session service.
+ *
+ * `getSession` returns the transcript as {@link projectTranscript} renders it
+ * for one named agent; every write goes to the REAL session held underneath,
+ * so the durable record keeps thoughts, tool calls and full payloads for
+ * long-term memory ingestion and for operators reading the row.
+ *
+ * Both views are kept live during a turn: the runner appends to the
+ * projected session it is holding (it re-reads `session.events` before every
+ * model call, so the agent's own in-flight tool calls must stay visible and
+ * unprojected), while the same event is appended and persisted to the real
+ * one. Only history is projected; the current turn never is.
+ *
+ * Construct one per turn — it is bound to a single agent name.
+ */
+export declare class ProjectedSessionService extends BaseSessionService {
+    private readonly inner;
+    private readonly forAgent;
+    private readonly options;
+    /** Real sessions handed out by `getSession`, keyed by identity. */
+    private readonly stored;
+    constructor(inner: BaseSessionService, forAgent: string, options?: ProjectionOptions);
+    private key;
+    createSession(request: CreateSessionRequest): Promise<Session>;
+    listSessions(request: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession(request: DeleteSessionRequest): Promise<void>;
+    getSession(request: GetSessionRequest): Promise<Session | undefined>;
+    appendEvent(request: {
+        session: Session;
+        event: Event;
+    }): Promise<Event>;
+}