melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/runtime/adkSessionBridge.js

@@ -0,0 +1,176 @@
+/**
+ * lib/runtime/adkSessionBridge.ts — one session store, either runtime
+ * (ADR 0045, ADR 0052, ADR 0058).
+ *
+ * WHY this file exists:
+ *   Until ADK leaves at 1.0, the ADK runtime asks for ADK's
+ *   BaseSessionService and the native runtime for the engine's
+ *   SessionService (lib/runtime/sessions.ts). The durable stores and the
+ *   transcript projection implement both, so they need no bridge. A store
+ *   that implements only one of them gets the other here:
+ *   - SessionServiceForAdk: the ADK runtime on an engine store, such as
+ *     InProcessSessionService.
+ *   - AdkSessionServiceForEngine: the engine's interface on an ADK store,
+ *     such as ADK's InMemorySessionService, with the interface's meaning
+ *     where ADK's store has another (sessions.ts, "ONE MEANING ACROSS
+ *     STORES").
+ *   asAdkSessionService and asSessionService hand a store back as it is
+ *   when it already implements the face asked for, and a bridge back as the
+ *   store it wraps, so a store bridged one way and then back is itself.
+ *   A surface that takes a store from its caller (the A2A executor and app,
+ *   the REPL) types it as EitherSessionService and asks for the face it
+ *   needs here (ADR 0080).
+ *
+ * APPEND: each face keeps its own runtime's rules for the caller's session.
+ *   The ADK face applies an event to the runner's session through ADK's
+ *   base service, write-order check and all, exactly as the durable stores
+ *   do, and the store records it on a copy. The engine face applies it
+ *   through applyEvent, which never changes the caller's event, and hands
+ *   ADK's store a copy.
+ *
+ * This module loads ADK at run time, so it is not one of the engine's leaf
+ * modules (tests/events.test.ts names those).
+ */
+import { BaseSessionService } from '@google/adk';
+import { applyEvent, listPage, listWindow, selectEvents, withoutTempKeys } from './sessions.js';
+/** Every method the engine's interface names. */
+export function isSessionService(value) {
+    const v = value;
+    return (typeof v === 'object' && v !== null &&
+        typeof v.create === 'function' && typeof v.get === 'function' && typeof v.list === 'function' &&
+        typeof v.delete === 'function' && typeof v.append === 'function');
+}
+/**
+ * Every method ADK's runner and services call. A duck check rather than
+ * instanceof, so a store built against another copy of ADK still counts.
+ */
+export function isAdkSessionService(value) {
+    const v = value;
+    return (typeof v === 'object' && v !== null &&
+        typeof v.createSession === 'function' && typeof v.getSession === 'function' &&
+        typeof v.listSessions === 'function' && typeof v.deleteSession === 'function' &&
+        typeof v.appendEvent === 'function');
+}
+/**
+ * A copy a store may apply an event to without touching the caller's
+ * session: applyEvent and ADK's base service change only `state`'s keys,
+ * the `events` array and `lastUpdateTime`.
+ */
+function shadowOf(session) {
+    return { ...session, state: { ...session.state }, events: [...session.events] };
+}
+/** The key fields only: a request object can carry more. */
+function keyOf(request) {
+    return { appName: request.appName, userId: request.userId, sessionId: request.sessionId };
+}
+// ── The ADK runtime on an engine store ───────────────────────────────────────
+/** ADK's BaseSessionService over an engine SessionService. */
+export class SessionServiceForAdk extends BaseSessionService {
+    service;
+    constructor(service) {
+        super();
+        this.service = service;
+    }
+    async createSession(request) {
+        return (await this.service.create(request));
+    }
+    async getSession(request) {
+        return (await this.service.get(keyOf(request), request.config));
+    }
+    async listSessions(request) {
+        return (await this.service.list(request));
+    }
+    async deleteSession(request) {
+        await this.service.delete(keyOf(request));
+    }
+    async appendEvent({ session, event }) {
+        if (event.partial)
+            return event;
+        // The store applies the event once, to the session as it stood.
+        const before = shadowOf(session);
+        await super.appendEvent({ session, event });
+        session.lastUpdateTime = event.timestamp;
+        await this.service.append(before, event);
+        return event;
+    }
+}
+// ── The engine's interface on an ADK store ───────────────────────────────────
+/** The engine's SessionService over an ADK BaseSessionService. */
+export class AdkSessionServiceForEngine {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    /** A session that exists comes back unchanged: ADK's own store would reset it. */
+    async create(request) {
+        if (request.sessionId) {
+            const existing = await this.get({ appName: request.appName, userId: request.userId, sessionId: request.sessionId });
+            if (existing)
+                return existing;
+        }
+        const created = await this.service.createSession({
+            appName: request.appName,
+            userId: request.userId,
+            sessionId: request.sessionId,
+            state: withoutTempKeys(request.state ?? {}),
+        });
+        return created;
+    }
+    /** Reads the whole session and filters it here, so `options` mean what the interface says. */
+    async get(key, options) {
+        const held = (await this.service.getSession(keyOf(key)));
+        if (!held)
+            return undefined;
+        return { ...held, events: selectEvents(held.events, options) };
+    }
+    /** The window goes to ADK's store as an offset; the paging figures are the interface's. */
+    async list(request) {
+        const { offset, limit } = listWindow(request);
+        const listed = await this.service.listSessions({
+            appName: request.appName,
+            userId: request.userId,
+            order: request.order,
+            offset,
+            limit,
+        });
+        return {
+            sessions: listed.sessions.map((s) => ({ ...s, events: [] })),
+            ...listPage(listed.totalItems, request),
+        };
+    }
+    async delete(key) {
+        await this.service.deleteSession(keyOf(key));
+    }
+    async append(session, event) {
+        if (event.partial)
+            return event;
+        // ADK's base service applies an event to the session it is given and
+        // rewrites the event's delta in place, so ADK's store gets copies of
+        // both, and the session as it stood.
+        const before = shadowOf(session);
+        const stored = applyEvent(session, event);
+        await this.service.appendEvent({ session: before, event: structuredClone(stored) });
+        return stored;
+    }
+}
+// ── Either face of a store ───────────────────────────────────────────────────
+/** The store as the ADK runtime takes it: itself when it already is one. */
+export function asAdkSessionService(service) {
+    if (service instanceof AdkSessionServiceForEngine)
+        return service.service;
+    if (isAdkSessionService(service))
+        return service;
+    if (isSessionService(service))
+        return new SessionServiceForAdk(service);
+    throw new TypeError('Not a session service: it implements neither SessionService nor ADK\'s BaseSessionService.');
+}
+/** The store as the engine's interface: itself when it already is one. */
+export function asSessionService(service) {
+    if (service instanceof SessionServiceForAdk)
+        return service.service;
+    if (isSessionService(service))
+        return service;
+    if (isAdkSessionService(service))
+        return new AdkSessionServiceForEngine(service);
+    throw new TypeError('Not a session service: it implements neither SessionService nor ADK\'s BaseSessionService.');
+}

package/dist/lib/runtime/credentials.d.ts

@@ -0,0 +1,59 @@
+/**
+ * lib/runtime/credentials.ts — reading and answering a tool's OAuth consent
+ * request in a session (WS6-3b, ADR 0085).
+ *
+ * A tool that needs a grant the person has not given asks for it
+ * (`ctx.requestCredential(provider)`). The run stores ADK's own
+ * `adk_request_credential` call, as ADK's generateAuthEvent writes it: args
+ * `{ function_call_id, auth_config }`, an `adk-` id listed in
+ * longRunningToolIds. The auth_config carries the authorization URL and the
+ * state nonce, never a client secret or a code verifier
+ * (lib/tools/oauthConsent.ts). The turn ends input-required with the
+ * request (`result.consent`).
+ *
+ * The person completes the flow in their browser; the server's callback
+ * stores the grant. Their next message, once the grant is stored, becomes a
+ * function response to the request (`credentialResponsePart`), and the
+ * agent's loop runs the paused call again before its next step
+ * (lib/runtime/native/interrupts.ts grantedCalls). Until the grant is
+ * stored, a message repeats the request and runs nothing.
+ */
+import type { Event } from '@google/adk';
+/** ADK's name for the credential request (REQUEST_CREDENTIAL_FUNCTION_CALL_NAME). */
+export declare const CREDENTIAL_REQUEST = "adk_request_credential";
+/** A paused call waiting for the person to grant a provider. */
+export interface PendingConsent {
+    /** The `adk_request_credential` call's id: what the answer names. */
+    id: string;
+    /** The agent whose call is paused. */
+    agent: string;
+    /** The paused call's id. */
+    functionCallId: string;
+    /** The provider, as the credential store names it (the AuthConfig's credentialKey). */
+    provider: string;
+    /** The authorization URL the person opens. */
+    authUri: string;
+    /** The state nonce the URL carries. */
+    state: string;
+    scopes: string[];
+}
+/** The request an `adk_request_credential` call carries, or undefined when it is not one this engine reads. */
+export declare function consentFrom(author: string | undefined, call: {
+    name?: string;
+    id?: string;
+    args?: Record<string, unknown>;
+}): PendingConsent | undefined;
+/**
+ * The consent request still waiting in a session, or undefined. One that is
+ * answered (a function response with its id), or that the person moved past
+ * with a text message, is not pending.
+ */
+export declare function pendingConsent(events: readonly Event[]): PendingConsent | undefined;
+/**
+ * The message part that answers request `id` once the grant is stored. It
+ * names the provider and carries no credential: the grant is in the
+ * credential store, and the resumed call reads it from there.
+ */
+export declare function credentialResponsePart(id: string, provider: string): Record<string, unknown>;
+/** One line a person can read: what they are asked to connect. */
+export declare function describeConsent(c: PendingConsent): string;

package/dist/lib/runtime/credentials.js

@@ -0,0 +1,62 @@
+/** ADK's name for the credential request (REQUEST_CREDENTIAL_FUNCTION_CALL_NAME). */
+export const CREDENTIAL_REQUEST = 'adk_request_credential';
+const partsOf = (e) => (e.content?.parts ?? []);
+const hasUserText = (e) => e.author === 'user' && partsOf(e).some((p) => typeof p.text === 'string' && p.text.trim() && !p.thought);
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The request an `adk_request_credential` call carries, or undefined when it is not one this engine reads. */
+export function consentFrom(author, call) {
+    if (call.name !== CREDENTIAL_REQUEST || !call.id || !isRecord(call.args))
+        return undefined;
+    const functionCallId = call.args.function_call_id ?? call.args.functionCallId;
+    const config = call.args.auth_config ?? call.args.authConfig;
+    if (typeof functionCallId !== 'string' || !isRecord(config))
+        return undefined;
+    const oauth2 = isRecord(config.exchangedAuthCredential) && isRecord(config.exchangedAuthCredential.oauth2) ? config.exchangedAuthCredential.oauth2 : {};
+    const flows = isRecord(config.authScheme) && isRecord(config.authScheme.flows) ? config.authScheme.flows : {};
+    const scopes = isRecord(flows.authorizationCode) && isRecord(flows.authorizationCode.scopes) ? Object.keys(flows.authorizationCode.scopes) : [];
+    return {
+        id: call.id,
+        agent: author ?? '',
+        functionCallId,
+        provider: typeof config.credentialKey === 'string' ? config.credentialKey : '',
+        authUri: typeof oauth2.authUri === 'string' ? oauth2.authUri : '',
+        state: typeof oauth2.state === 'string' ? oauth2.state : '',
+        scopes,
+    };
+}
+/**
+ * The consent request still waiting in a session, or undefined. One that is
+ * answered (a function response with its id), or that the person moved past
+ * with a text message, is not pending.
+ */
+export function pendingConsent(events) {
+    const answered = new Set();
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (hasUserText(e))
+            return undefined;
+        for (const p of partsOf(e)) {
+            if (p.functionResponse?.name === CREDENTIAL_REQUEST && p.functionResponse.id)
+                answered.add(p.functionResponse.id);
+        }
+        for (const p of partsOf(e)) {
+            const call = p.functionCall;
+            if (call?.name !== CREDENTIAL_REQUEST || !call.id || answered.has(call.id))
+                continue;
+            return consentFrom(e.author, call);
+        }
+    }
+    return undefined;
+}
+/**
+ * The message part that answers request `id` once the grant is stored. It
+ * names the provider and carries no credential: the grant is in the
+ * credential store, and the resumed call reads it from there.
+ */
+export function credentialResponsePart(id, provider) {
+    return { functionResponse: { id, name: CREDENTIAL_REQUEST, response: { credentialKey: provider, granted: true } } };
+}
+/** One line a person can read: what they are asked to connect. */
+export function describeConsent(c) {
+    return `${c.agent} needs access to your ${c.provider} account`;
+}

package/dist/lib/runtime/events.d.ts

@@ -0,0 +1,229 @@
+/**
+ * lib/runtime/events.ts — the engine's own event type: one step of a
+ * conversation as a session stores it (ADR 0045, ADR 0052).
+ *
+ * WHY this file exists:
+ *   The native runtime reads and writes the sessions ADK wrote, and the
+ *   stored Event JSON in adk_sessions.events and adk_session_events is one of
+ *   the four shapes ADR 0045 fixes. So the engine's event is not a new
+ *   format: TurnEvent IS that JSON, typed. Every field the engine reads has
+ *   ADK's name, position in the object and meaning, and a TurnEvent
+ *   serializes to the bytes ADK would have stored (tests/events.test.ts
+ *   proves it on every session fixture, in both stored forms). The content
+ *   stays @google/genai `Content` in shape, described here structurally;
+ *   the model contract (lib/models/contract.ts) is what a model call speaks,
+ *   reached through lib/models/genaiMapping.ts (ADR 0048 item 8).
+ *
+ * THE PARSE CARRIES EVERYTHING:
+ *   parseTurnEvent checks the type of every field this file declares and
+ *   returns the same object, never a projection. A field ADK writes that the
+ *   engine does not know (a live-streaming field, a part's videoMetadata, the
+ *   camelCase toolCall some providers emit) is kept as it is, in place. That
+ *   matters because the Supabase service rewrites a conversation's whole
+ *   events array on every append: a parse that dropped an unknown field would
+ *   erase it from every stored row the native runtime touched. It rejects
+ *   only what the engine cannot read, with the path of the field and the
+ *   type it found, never the value, since events hold what people said.
+ *
+ * NO RUNTIME IMPORTS: every import here is a type. Nothing in this module's
+ * import graph names @google/* (tests/events.test.ts asserts it), so the
+ * native runtime can read sessions with ADK uninstalled.
+ */
+import type { ProviderState } from '../models/contract.ts';
+/** A tool call the model made: `part.functionCall`. */
+export interface TurnFunctionCall {
+    /** ADK's `adk-<uuid>`, or the provider's id. Absent in a request ADK built: it strips its own ids. */
+    id?: string;
+    name?: string;
+    args?: Record<string, unknown>;
+}
+/** A tool's answer: `part.functionResponse`. */
+export interface TurnFunctionResponse {
+    /** The id of the call it answers. */
+    id?: string;
+    name?: string;
+    /**
+     * ADK wraps a result that is not an object as `{ result }`. In a trimmed
+     * row a result over 2,000 characters is `{ elided: '<size> chars dropped
+     * before storage — …' }` (trimEventForStorage, lib/session/transcript.ts).
+     */
+    response?: Record<string, unknown>;
+}
+/** One part of a content: genai's `Part`, with the fields the engine reads or writes. */
+export interface TurnPart {
+    text?: string;
+    /** The text is the model's reasoning, shown but never replayed as speech. */
+    thought?: boolean;
+    /** Gemini's opaque signature. A trimmed row keeps only a call's, as `skip_thought_signature_validator`. */
+    thoughtSignature?: string;
+    functionCall?: TurnFunctionCall;
+    functionResponse?: TurnFunctionResponse;
+    inlineData?: {
+        mimeType?: string;
+        data?: string;
+        displayName?: string;
+    };
+    fileData?: {
+        mimeType?: string;
+        fileUri?: string;
+        displayName?: string;
+    };
+    executableCode?: {
+        code?: string;
+        language?: string;
+    };
+    codeExecutionResult?: {
+        outcome?: string;
+        output?: string;
+    };
+    /** Another provider's reasoning state (ADR 0046), stored whole on the part it belongs before. */
+    providerState?: ProviderState;
+}
+export interface TurnContent {
+    /** `user` or `model`. A tool's answer is a `user` content; ADK's confirmation request is too. */
+    role?: string;
+    parts?: TurnPart[];
+}
+/** A pending approval, keyed in `requestedToolConfirmations` by the gated call's id. */
+export interface TurnToolConfirmation {
+    hint?: string;
+    confirmed?: boolean;
+    payload?: unknown;
+}
+/**
+ * What the event does besides speak: ADK's `EventActions`. ADK writes the
+ * four dictionaries on every event (createTurnEvent does too); they are
+ * optional here because a reader must not fail on a row that lacks one.
+ */
+export interface TurnEventActions {
+    /** State writes. `temp:` keys never reach a store (applyEvent, lib/runtime/sessions.ts). */
+    stateDelta?: Record<string, unknown>;
+    /** Artifact name to version. */
+    artifactDelta?: Record<string, number>;
+    /** Auth configurations a tool asked for, by call id. */
+    requestedAuthConfigs?: Record<string, unknown>;
+    /** Approvals asked for, by the gated call's id (ADR 0028). */
+    requestedToolConfirmations?: Record<string, TurnToolConfirmation>;
+    /** The run ends on this tool response, without a model call to summarize it. */
+    skipSummarization?: boolean;
+    transferToAgent?: string;
+    escalate?: boolean;
+    /** A workflow node's checkpointed input, read back when a paused workflow resumes (ADR 0030). */
+    agentState?: Record<string, unknown>;
+    endOfAgent?: boolean;
+}
+/**
+ * `usageMetadata`, in Gemini's meanings: `candidatesTokenCount` excludes the
+ * thinking counted in `thoughtsTokenCount`. The turn runner sums it per
+ * turn: the largest prompt, every completion, every thought.
+ */
+export interface TurnUsage {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+    cachedContentTokenCount?: number;
+    toolUsePromptTokenCount?: number;
+}
+/** Where a workflow event came from (ADR 0030). */
+export interface TurnNodeInfo {
+    /** The node path, e.g. `Pipeline.Triage`; the root's has no dot. */
+    path?: string;
+    outputFor?: string[];
+    messageAsOutput?: boolean;
+}
+export type TurnRouteKey = string | number | boolean;
+/**
+ * One event of a session: the stored ADK Event JSON, typed. The first group
+ * is what the engine reads to run and resume a turn; the second is what ADK
+ * writes beside it, which the engine stores and reads back unchanged.
+ */
+export interface TurnEvent {
+    /** Eight letters and digits (newEventId). An append with an id already in the session replaces that event. */
+    id: string;
+    /** Every event of one run shares it. ADK writes `e-<uuid>`. */
+    invocationId: string;
+    /** `user`, or the name of the agent or workflow node that wrote it. */
+    author?: string;
+    /** Absent on an event that only carries actions (a workflow's pause marker). */
+    content?: TurnContent;
+    actions: TurnEventActions;
+    /** A streaming fragment: shown, never stored. */
+    partial?: boolean;
+    /** The model finished this response. */
+    turnComplete?: boolean;
+    /** Milliseconds since the epoch. */
+    timestamp: number;
+    /** Labels an adapter attaches, e.g. `responses.server_tool_calls`; JSON only. */
+    customMetadata?: Record<string, unknown>;
+    /** Ids of this event's calls that wait for a person (`ask_user`, a workflow's input request). */
+    longRunningToolIds?: string[];
+    /** `parent.child` path that keeps a subagent's events from its peers. */
+    branch?: string;
+    /**
+     * A failure. Gemini reports its finish or block reason here, and `STOP` is
+     * not a failure: the turn runner ignores an error whose code is `STOP`.
+     */
+    errorCode?: string;
+    errorMessage?: string;
+    usageMetadata?: TurnUsage;
+    /** Gemini's finish reason, e.g. `STOP`. */
+    finishReason?: string;
+    /** Gemini search grounding: queries and sources (lib/grounding.ts reads it). */
+    groundingMetadata?: object;
+    citationMetadata?: object;
+    /** A live session was interrupted mid-answer. */
+    interrupted?: boolean;
+    modelVersion?: string;
+    /** A workflow node's result (ADR 0030). */
+    output?: unknown;
+    /** The route a workflow routing node chose. */
+    route?: TurnRouteKey | TurnRouteKey[];
+    nodeInfo?: TurnNodeInfo;
+    isolationScope?: string;
+}
+/** The event's tool calls, in order: the parts' `functionCall` objects themselves, not copies. */
+export declare function getFunctionCalls(event: TurnEvent): TurnFunctionCall[];
+/** The event's tool responses, in order: the parts' `functionResponse` objects themselves. */
+export declare function getFunctionResponses(event: TurnEvent): TurnFunctionResponse[];
+/** The last part is a code execution result: the model has more to say about it. */
+export declare function hasTrailingCodeExecutionResult(event: TurnEvent): boolean;
+/**
+ * The event ends its agent's run: ADK's `isFinalResponse`, case for case.
+ *
+ * Final at once when the run is meant to stop on it: a tool response that
+ * skips summarization (an approval request), a call that waits for a person
+ * (long-running ids), or a tool asking for auth. Otherwise final when it
+ * carries no tool call, no tool response, is not a streaming fragment, and
+ * does not end on a code execution result.
+ */
+export declare function isFinal(event: TurnEvent): boolean;
+/** A new event id: eight letters and digits, as ADK makes them. */
+export declare function newEventId(): string;
+/** Actions with ADK's four dictionaries present, then `actions` over them. */
+export declare function createEventActions(actions?: TurnEventActions): TurnEventActions;
+/** What createTurnEvent takes: any field, every one optional. */
+export type TurnEventInit = Partial<Omit<TurnEvent, 'actions'>> & {
+    actions?: TurnEventActions;
+};
+/**
+ * A new event, built as ADK's `createEvent` builds one, so it serializes to
+ * the same JSON, key order included: the given fields first, then the
+ * defaults in ADK's order (an id, an empty invocation id, the four action
+ * dictionaries, no long-running ids, the time now).
+ */
+export declare function createTurnEvent(init?: TurnEventInit): TurnEvent;
+/** A stored event the engine cannot read, and where in it. */
+export declare class TurnEventError extends Error {
+    /** e.g. `events[3].content.parts[0].functionCall.name` */
+    readonly path: string;
+    constructor(path: string, problem: string);
+}
+/**
+ * A stored event, checked: the same object, typed. Throws TurnEventError
+ * naming the first field the engine cannot read. Nothing is copied, added,
+ * dropped or reordered, so `JSON.stringify` of the result is the stored JSON.
+ */
+export declare function parseTurnEvent(value: unknown, path?: string): TurnEvent;
+/** A stored events array (a session's `events`, or a row's), checked the same way. */
+export declare function parseTurnEvents(value: unknown, path?: string): TurnEvent[];