melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/runtime/questions.js

@@ -1,42 +1,22 @@
-/**
- * lib/runtime/questions.ts — an agent asks the person a question mid-turn,
- * and the next message is the answer.
- *
- * WHY: A syndicate that is put in front of users needs to ask: "which of
- * these three accounts?", "what is the order number?". Before this, an
- * agent could only end its turn with a question in its text and hope the
- * next message answered it, with nothing in the session saying a question
- * was open. `ask_user` is ADK's long-running tool mechanism under one YAML
- * name: the call is recorded, the run ends without a response to it, the
- * turn ends `input-required` (`result.input`), and the next message on the
- * conversation becomes the call's response, so the agent resumes its own
- * tool loop where it asked, with the question and the answer side by side
- * in its history.
- *
- * The same `input-required` path carries a workflow's `ask_user` node
- * (lib/workflow.ts) and an approval (ADR 0028); a client handles all three
- * by showing `result.input` (or the approval) and sending the next message.
- *
- * WHERE: only on an agent the turn runs directly (the orchestrator, or a
- * plan-dispatch route), as with approval gates: inside a delegated
- * subagent ADK swallows the pause. Not inside a workflow node yet. The
- * schema refuses both.
- */
-import { LongRunningFunctionTool } from '@google/adk';
 import { z } from 'zod';
+import { defineTool } from '../tools/toolContract.js';
+import { inputRequestFrom } from '../workflowConfig.js';
 /** The registry name, and the function-call name an open question carries. */
 export const ASK_USER = 'ask_user';
 export const MAX_OPTIONS = 10;
 /**
- * The tool. Its execute returns nothing: a long-running call with no result
- * ends the run, and ADK waits for a function response with the call's id.
+ * The tool, an own Tool marked long-running; the registry hands the ADK
+ * runtime its FunctionTool (lib/tools/adkTool.ts). Its execute returns
+ * nothing: a long-running call with no result ends the run, and the runtime
+ * waits for a function response with the call's id.
  */
-export const askUserTool = new LongRunningFunctionTool({
+export const askUserTool = defineTool({
     name: ASK_USER,
+    longRunning: true,
     description: 'Ask the person one question and wait for their answer before you continue: a missing detail you need, or a choice only they can make. ' +
         'Pass `options` when the answer is one of a few choices. The turn ends here; the person\'s next message is the answer, returned to you as this call\'s result. ' +
         'Ask only what you cannot find out or reasonably assume, one question per call.',
-    parameters: z.object({
+    schema: z.object({
         question: z.string().min(1).max(500).describe('The question, as the person will read it.'),
         options: z
             .array(z.string().min(1).max(120))
@@ -45,9 +25,8 @@ export const askUserTool = new LongRunningFunctionTool({
             .describe('The choices, when the answer is one of a few. Omit for a free answer.'),
     }),
     execute: async (_args, context) => {
-        if (context)
-            context.actions.skipSummarization = true;
-        return null;
+        context.actions.skipSummarization = true;
+        return undefined;
     },
 });
 const partsOf = (e) => (e.content?.parts ?? []);
@@ -69,6 +48,9 @@ export function questionFrom(author, call) {
  * The question still waiting for an answer in a session, or undefined. A
  * question the person moved past (a text message after it was answered)
  * is not pending; an answered one carries a function response with its id.
+ * Only an agent asks: an `ask_user` call in an event the user authored is
+ * no question, so the next message never becomes its answer (as approvals
+ * refuse a user-authored request, ADR 0077; ADR 0088).
  */
 export function pendingQuestion(events) {
     const answered = new Set();
@@ -80,6 +62,8 @@ export function pendingQuestion(events) {
             if (p.functionResponse?.name === ASK_USER && p.functionResponse.id)
                 answered.add(p.functionResponse.id);
         }
+        if (e.author === 'user')
+            continue;
         for (const p of partsOf(e)) {
             const call = p.functionCall;
             if (call?.name !== ASK_USER || !call.id || answered.has(call.id))
@@ -89,6 +73,37 @@ export function pendingQuestion(events) {
     }
     return undefined;
 }
+/**
+ * The workflow question (`adk_request_input`, an ask_user node's request)
+ * still open in a session's events, or undefined. The answer is stored as
+ * the person's next text message, not as a function response, so a text
+ * message after the question closes it; a function response with its id
+ * answers it too. As with pendingQuestion, only a node asks: a request in
+ * an event the user authored is none. The resume (lib/workflow/resume.ts)
+ * reads the same events to route the answer.
+ */
+export function pendingWorkflowInput(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?.id)
+                answered.add(p.functionResponse.id);
+        if (e.author === 'user')
+            continue;
+        for (const p of partsOf(e)) {
+            const call = p.functionCall;
+            if (!call || (call.id && answered.has(call.id)))
+                continue;
+            const input = inputRequestFrom(e.author, call);
+            if (input)
+                return input;
+        }
+    }
+    return undefined;
+}
 /** The message part that answers question `id` with the person's text. */
 export function questionAnswerPart(id, answer) {
     return { functionResponse: { id, name: ASK_USER, response: { result: answer } } };

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

@@ -0,0 +1,30 @@
+/**
+ * lib/runtime/runtimeFlag.ts — which runtime runs a turn: MELCHIZEDEK_RUNTIME
+ * and the turn's `runtime` option (ADR 0045, ADR 0073).
+ *
+ * `adk` runs each agent on Google ADK's Runner, `native` on the engine's own
+ * agent loop (lib/runtime/native/agentLoop.ts). The default is `adk` until
+ * the release that makes native the default (ADR 0045). A feature the native
+ * runtime does not run yet fails before any model call with
+ * UnsupportedOnRuntimeError, which names the feature and the runtime.
+ *
+ * A leaf module: it imports nothing, so every caller (the compiler, the
+ * turn runner, the wiki agent runner) can read the flag without a cycle.
+ */
+/** The runtime a turn runs on: Google ADK's Runner, or the engine's own loop. */
+export type RuntimeName = 'adk' | 'native';
+export declare const RUNTIMES: readonly RuntimeName[];
+/** The runtime when neither the turn nor MELCHIZEDEK_RUNTIME names one. */
+export declare const DEFAULT_RUNTIME: RuntimeName;
+/** MELCHIZEDEK_RUNTIME as set, or undefined when unset or blank. Any other value is a configuration error. */
+export declare function runtimeSetting(env?: NodeJS.ProcessEnv): RuntimeName | undefined;
+/** The runtime to use: the caller's option, else MELCHIZEDEK_RUNTIME, else adk. */
+export declare function chooseRuntime(option?: string, env?: NodeJS.ProcessEnv): RuntimeName;
+/** A feature the chosen runtime does not run yet. Thrown before any model call. */
+export declare class UnsupportedOnRuntimeError extends Error {
+    readonly feature: string;
+    readonly runtime: RuntimeName;
+    constructor(feature: string, runtime: RuntimeName, where: string);
+}
+/** The error for a feature the native runtime does not run yet; `where` names the agent or syndicate. */
+export declare function unsupportedOnNative(feature: string, where: string): UnsupportedOnRuntimeError;

package/dist/lib/runtime/runtimeFlag.js

@@ -0,0 +1,50 @@
+/**
+ * lib/runtime/runtimeFlag.ts — which runtime runs a turn: MELCHIZEDEK_RUNTIME
+ * and the turn's `runtime` option (ADR 0045, ADR 0073).
+ *
+ * `adk` runs each agent on Google ADK's Runner, `native` on the engine's own
+ * agent loop (lib/runtime/native/agentLoop.ts). The default is `adk` until
+ * the release that makes native the default (ADR 0045). A feature the native
+ * runtime does not run yet fails before any model call with
+ * UnsupportedOnRuntimeError, which names the feature and the runtime.
+ *
+ * A leaf module: it imports nothing, so every caller (the compiler, the
+ * turn runner, the wiki agent runner) can read the flag without a cycle.
+ */
+export const RUNTIMES = ['adk', 'native'];
+/** The runtime when neither the turn nor MELCHIZEDEK_RUNTIME names one. */
+export const DEFAULT_RUNTIME = 'adk';
+function asRuntime(raw, source) {
+    const value = raw.trim().toLowerCase();
+    if (value === 'adk' || value === 'native')
+        return value;
+    throw new Error(`${source} must be "adk" or "native".`);
+}
+/** MELCHIZEDEK_RUNTIME as set, or undefined when unset or blank. Any other value is a configuration error. */
+export function runtimeSetting(env = process.env) {
+    const raw = env.MELCHIZEDEK_RUNTIME;
+    if (!raw || !raw.trim())
+        return undefined;
+    return asRuntime(raw, 'MELCHIZEDEK_RUNTIME');
+}
+/** The runtime to use: the caller's option, else MELCHIZEDEK_RUNTIME, else adk. */
+export function chooseRuntime(option, env = process.env) {
+    if (option !== undefined)
+        return asRuntime(option, 'The runtime option');
+    return runtimeSetting(env) ?? DEFAULT_RUNTIME;
+}
+/** A feature the chosen runtime does not run yet. Thrown before any model call. */
+export class UnsupportedOnRuntimeError extends Error {
+    feature;
+    runtime;
+    constructor(feature, runtime, where) {
+        super(`${where}: ${feature} is not supported on the ${runtime} runtime yet. Run it on the ${runtime === 'native' ? 'adk' : 'native'} runtime (MELCHIZEDEK_RUNTIME, or the turn's runtime option).`);
+        this.name = 'UnsupportedOnRuntimeError';
+        this.feature = feature;
+        this.runtime = runtime;
+    }
+}
+/** The error for a feature the native runtime does not run yet; `where` names the agent or syndicate. */
+export function unsupportedOnNative(feature, where) {
+    return new UnsupportedOnRuntimeError(feature, 'native', where);
+}

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

@@ -0,0 +1,166 @@
+/**
+ * lib/runtime/sessions.ts — the engine's own session interface, the rules
+ * every store applies, and a store that lives in the process (ADR 0045,
+ * ADR 0052).
+ *
+ * WHY this file exists:
+ *   The native runtime reads and writes sessions without ADK. The durable
+ *   stores (lib/session/supabaseSessionService.ts, lib/storage/postgres/
+ *   sessionService.ts) and the transcript projection (lib/session/
+ *   transcript.ts) implement SessionService beside ADK's BaseSessionService,
+ *   and lib/runtime/adkSessionBridge.ts gives a store that has only one of
+ *   the two the other, until ADK leaves at 1.0 (ADR 0058). The shapes are
+ *   ADK's JSON (a Session holds TurnEvents, lib/runtime/events.ts), so both
+ *   runtimes read and write the same rows.
+ *
+ * ONE MEANING ACROSS STORES:
+ *   Where ADK's own services disagree with the engine's durable stores, the
+ *   interface takes the durable stores' meaning, because that is what
+ *   production runs and what a test on this in-process store should see.
+ *   Where the two durable stores differ, it takes the Postgres store's,
+ *   which never loses an event:
+ *   - `afterTimestamp` keeps events strictly after it, and `numRecentEvents`
+ *     then keeps the newest of those (ADK's in-memory store counts first
+ *     and keeps an event at the timestamp itself).
+ *   - Creating a session whose id exists returns it unchanged, events and
+ *     all, so a second create never resets a conversation (ADK's in-memory
+ *     store resets it).
+ *   - Paging reports at least one page (listPage).
+ *   - `app:` and `user:` state keys stay in the session's own state, as both
+ *     durable stores keep them; ADK's in-memory store shares them across
+ *     sessions. No syndicate writes such a key.
+ *   The method names are not ADK's (create, not createSession), so one class
+ *   can implement this interface and extend ADK's base during the dual
+ *   period without either signature constraining the other.
+ *
+ * NO RUNTIME IMPORTS: every import here is a type, and nothing in this
+ * module's import graph names @google/* (tests/events.test.ts asserts it).
+ */
+import type { TurnEvent } from './events.ts';
+/** A conversation's address. Stores key it as `<appName>:<userId>:<sessionId>`. */
+export interface SessionKey {
+    /** The syndicate (or, for a DELEGATE subagent's own row, the subagent's name). */
+    appName: string;
+    userId: string;
+    sessionId: string;
+}
+/** A conversation: the same JSON as ADK's `Session`. */
+export interface Session {
+    id: string;
+    appName: string;
+    userId: string;
+    /** Written only through events' `stateDelta` (applyEvent). Never holds a `temp:` key. */
+    state: Record<string, unknown>;
+    /** Oldest first. */
+    events: TurnEvent[];
+    /** Milliseconds since the epoch: the last appended event's timestamp, or the creation time. */
+    lastUpdateTime: number;
+}
+export interface CreateSessionRequest {
+    appName: string;
+    userId: string;
+    /** A new UUID when absent. */
+    sessionId?: string;
+    /** Initial state; `temp:` keys are dropped. */
+    state?: Record<string, unknown>;
+}
+export interface GetSessionOptions {
+    /** Keep only the newest N events (after `afterTimestamp`, when both are set). Ignored unless above zero. */
+    numRecentEvents?: number;
+    /** Keep only events whose timestamp is strictly greater. Ignored when 0 or absent. */
+    afterTimestamp?: number;
+}
+export interface ListSessionsRequest {
+    appName: string;
+    /** Every user's sessions when absent. */
+    userId?: string;
+    /** Page size. Every session matching, in one page, when absent. */
+    limit?: number;
+    /** Zero-based index of the first session. Ignored when `page` and `limit` are both set. */
+    offset?: number;
+    /** One-based page number. Needs `limit`; wins over `offset`. */
+    page?: number;
+    /** By last update, ties by id. Insertion order when absent. */
+    order?: 'asc' | 'desc';
+}
+export interface ListSessionsResult {
+    /** The page's sessions, each without its events. */
+    sessions: Session[];
+    /** One-based. */
+    page: number;
+    /** The page size, or every matching session's count when no limit was asked for. */
+    limit: number;
+    /** Sessions matching, across every page. */
+    totalItems: number;
+    /** At least 1. */
+    totalPages: number;
+}
+/**
+ * Where conversations live. Every method fails by throwing, with a message a
+ * person can act on; reading a session that does not exist is not a failure.
+ */
+export interface SessionService {
+    create(request: CreateSessionRequest): Promise<Session>;
+    /** A copy: changing it changes nothing stored. Undefined when there is no such session. */
+    get(key: SessionKey, options?: GetSessionOptions): Promise<Session | undefined>;
+    list(request: ListSessionsRequest): Promise<ListSessionsResult>;
+    /** Deletes the session and its events. Deleting one that does not exist does nothing. */
+    delete(key: SessionKey): Promise<void>;
+    /**
+     * Records `event` in `session` (applyEvent's rules, on the caller's copy)
+     * and in the store, and returns the event as stored. A partial event is
+     * returned as it is and recorded nowhere. Two copies of one session
+     * appending in turn both land: each append adds its own event.
+     */
+    append(session: Session, event: TurnEvent): Promise<TurnEvent>;
+}
+/** State keys with this prefix last for one invocation and are never stored. */
+export declare const TEMP_STATE_PREFIX = "temp:";
+/** A copy of `record` without its `temp:` keys, in the same key order. */
+export declare function withoutTempKeys(record: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Applies one event to a live session, as ADK's BaseSessionService does,
+ * and returns the event as a store keeps it:
+ *   1. A partial event is returned as it is, and the session is untouched.
+ *   2. The stored event's `stateDelta` loses its `temp:` keys (a copy; the
+ *      given event is never changed).
+ *   3. Each remaining delta key is written into `session.state`.
+ *   4. The event replaces the session's event with the same id, or is
+ *      appended.
+ *   5. `session.lastUpdateTime` becomes the event's timestamp.
+ */
+export declare function applyEvent(session: Session, event: TurnEvent): TurnEvent;
+/** The events a read with `options` returns, oldest first (GetSessionOptions). */
+export declare function selectEvents(events: readonly TurnEvent[], options?: GetSessionOptions): TurnEvent[];
+/**
+ * The window a list request asks for: a zero-based offset and, when a limit
+ * was given, the page size. `page` wins over `offset` only beside a limit.
+ */
+export declare function listWindow(request: Pick<ListSessionsRequest, 'limit' | 'offset' | 'page'>): {
+    offset: number;
+    limit?: number;
+};
+/** The paging figures a list result reports, given how many sessions matched. */
+export declare function listPage(totalItems: number, request: Pick<ListSessionsRequest, 'limit' | 'offset' | 'page'>): Omit<ListSessionsResult, 'sessions'>;
+export interface InProcessSessionOptions {
+    /** The clock for a new session's lastUpdateTime. Default Date.now. */
+    now?: () => number;
+}
+/**
+ * Sessions held in this process, lost when it exits: the store for a
+ * syndicate with no durable one, and for tests. Every read hands out a copy
+ * and every append stores a copy, so no caller shares an object with the
+ * store. An append to a session the store does not hold (deleted while its
+ * turn ran) keeps the caller's session as it stands after the event.
+ */
+export declare class InProcessSessionService implements SessionService {
+    private readonly sessions;
+    private readonly now;
+    constructor(options?: InProcessSessionOptions);
+    private static key;
+    create(request: CreateSessionRequest): Promise<Session>;
+    get(key: SessionKey, options?: GetSessionOptions): Promise<Session | undefined>;
+    list(request: ListSessionsRequest): Promise<ListSessionsResult>;
+    delete(key: SessionKey): Promise<void>;
+    append(session: Session, event: TurnEvent): Promise<TurnEvent>;
+}

package/dist/lib/runtime/sessions.js

@@ -0,0 +1,201 @@
+/**
+ * lib/runtime/sessions.ts — the engine's own session interface, the rules
+ * every store applies, and a store that lives in the process (ADR 0045,
+ * ADR 0052).
+ *
+ * WHY this file exists:
+ *   The native runtime reads and writes sessions without ADK. The durable
+ *   stores (lib/session/supabaseSessionService.ts, lib/storage/postgres/
+ *   sessionService.ts) and the transcript projection (lib/session/
+ *   transcript.ts) implement SessionService beside ADK's BaseSessionService,
+ *   and lib/runtime/adkSessionBridge.ts gives a store that has only one of
+ *   the two the other, until ADK leaves at 1.0 (ADR 0058). The shapes are
+ *   ADK's JSON (a Session holds TurnEvents, lib/runtime/events.ts), so both
+ *   runtimes read and write the same rows.
+ *
+ * ONE MEANING ACROSS STORES:
+ *   Where ADK's own services disagree with the engine's durable stores, the
+ *   interface takes the durable stores' meaning, because that is what
+ *   production runs and what a test on this in-process store should see.
+ *   Where the two durable stores differ, it takes the Postgres store's,
+ *   which never loses an event:
+ *   - `afterTimestamp` keeps events strictly after it, and `numRecentEvents`
+ *     then keeps the newest of those (ADK's in-memory store counts first
+ *     and keeps an event at the timestamp itself).
+ *   - Creating a session whose id exists returns it unchanged, events and
+ *     all, so a second create never resets a conversation (ADK's in-memory
+ *     store resets it).
+ *   - Paging reports at least one page (listPage).
+ *   - `app:` and `user:` state keys stay in the session's own state, as both
+ *     durable stores keep them; ADK's in-memory store shares them across
+ *     sessions. No syndicate writes such a key.
+ *   The method names are not ADK's (create, not createSession), so one class
+ *   can implement this interface and extend ADK's base during the dual
+ *   period without either signature constraining the other.
+ *
+ * NO RUNTIME IMPORTS: every import here is a type, and nothing in this
+ * module's import graph names @google/* (tests/events.test.ts asserts it).
+ */
+// ── The rules every store applies ────────────────────────────────────────────
+/** State keys with this prefix last for one invocation and are never stored. */
+export const TEMP_STATE_PREFIX = 'temp:';
+/**
+ * Sets an own property even when the key is `__proto__`: JSON.parse makes
+ * that an own key, and plain assignment would re-parent the object instead.
+ */
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** A copy of `record` without its `temp:` keys, in the same key order. */
+export function withoutTempKeys(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record))
+        if (!key.startsWith(TEMP_STATE_PREFIX))
+            setOwn(out, key, value);
+    return out;
+}
+/**
+ * Applies one event to a live session, as ADK's BaseSessionService does,
+ * and returns the event as a store keeps it:
+ *   1. A partial event is returned as it is, and the session is untouched.
+ *   2. The stored event's `stateDelta` loses its `temp:` keys (a copy; the
+ *      given event is never changed).
+ *   3. Each remaining delta key is written into `session.state`.
+ *   4. The event replaces the session's event with the same id, or is
+ *      appended.
+ *   5. `session.lastUpdateTime` becomes the event's timestamp.
+ */
+export function applyEvent(session, event) {
+    if (event.partial)
+        return event;
+    let stored = event;
+    const delta = event.actions?.stateDelta;
+    if (delta) {
+        const kept = withoutTempKeys(delta);
+        if (Object.keys(kept).length !== Object.keys(delta).length) {
+            stored = { ...event, actions: { ...event.actions, stateDelta: kept } };
+        }
+        for (const [key, value] of Object.entries(kept))
+            setOwn(session.state, key, value);
+    }
+    const at = session.events.findIndex((e) => e.id === stored.id);
+    if (at >= 0)
+        session.events[at] = stored;
+    else
+        session.events.push(stored);
+    session.lastUpdateTime = stored.timestamp;
+    return stored;
+}
+/** A finite number, rounded down; undefined otherwise. */
+function whole(n) {
+    return typeof n === 'number' && Number.isFinite(n) ? Math.floor(n) : undefined;
+}
+/** The events a read with `options` returns, oldest first (GetSessionOptions). */
+export function selectEvents(events, options = {}) {
+    let out = [...events];
+    const after = options.afterTimestamp;
+    if (after)
+        out = out.filter((e) => e.timestamp > after);
+    const n = whole(options.numRecentEvents);
+    if (n !== undefined && n > 0)
+        out = out.slice(-n);
+    return out;
+}
+/**
+ * The window a list request asks for: a zero-based offset and, when a limit
+ * was given, the page size. `page` wins over `offset` only beside a limit.
+ */
+export function listWindow(request) {
+    const limitRaw = whole(request.limit);
+    const limit = limitRaw === undefined ? undefined : Math.max(0, limitRaw);
+    const page = whole(request.page);
+    const offset = limit !== undefined && page !== undefined ? (Math.max(1, page) - 1) * limit : Math.max(0, whole(request.offset) ?? 0);
+    return limit === undefined ? { offset } : { offset, limit };
+}
+/** The paging figures a list result reports, given how many sessions matched. */
+export function listPage(totalItems, request) {
+    const { offset, limit } = listWindow(request);
+    return {
+        page: limit ? Math.floor(offset / limit) + 1 : 1,
+        limit: limit ?? totalItems,
+        totalItems,
+        totalPages: limit ? Math.max(1, Math.ceil(totalItems / limit)) : 1,
+    };
+}
+/**
+ * Sessions held in this process, lost when it exits: the store for a
+ * syndicate with no durable one, and for tests. Every read hands out a copy
+ * and every append stores a copy, so no caller shares an object with the
+ * store. An append to a session the store does not hold (deleted while its
+ * turn ran) keeps the caller's session as it stands after the event.
+ */
+export class InProcessSessionService {
+    sessions = new Map();
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+    }
+    static key(appName, userId, sessionId) {
+        return JSON.stringify([appName, userId, sessionId]);
+    }
+    async create(request) {
+        const id = request.sessionId || globalThis.crypto.randomUUID();
+        const key = InProcessSessionService.key(request.appName, request.userId, id);
+        const existing = this.sessions.get(key);
+        if (existing)
+            return structuredClone(existing);
+        const session = {
+            id,
+            appName: request.appName,
+            userId: request.userId,
+            state: withoutTempKeys(structuredClone(request.state ?? {})),
+            events: [],
+            lastUpdateTime: this.now(),
+        };
+        this.sessions.set(key, session);
+        return structuredClone(session);
+    }
+    async get(key, options) {
+        const held = this.sessions.get(InProcessSessionService.key(key.appName, key.userId, key.sessionId));
+        if (!held)
+            return undefined;
+        const copy = structuredClone(held);
+        copy.events = selectEvents(copy.events, options);
+        return copy;
+    }
+    async list(request) {
+        const matching = [...this.sessions.values()].filter((s) => s.appName === request.appName && (request.userId === undefined || s.userId === request.userId));
+        if (request.order) {
+            const sign = request.order === 'asc' ? 1 : -1;
+            matching.sort((a, b) => sign * (a.lastUpdateTime - b.lastUpdateTime) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        }
+        const { offset, limit } = listWindow(request);
+        const window = matching.slice(offset, limit === undefined ? undefined : offset + limit);
+        return {
+            sessions: window.map((s) => ({
+                id: s.id,
+                appName: s.appName,
+                userId: s.userId,
+                state: structuredClone(s.state),
+                events: [],
+                lastUpdateTime: s.lastUpdateTime,
+            })),
+            ...listPage(matching.length, request),
+        };
+    }
+    async delete(key) {
+        this.sessions.delete(InProcessSessionService.key(key.appName, key.userId, key.sessionId));
+    }
+    async append(session, event) {
+        if (event.partial)
+            return event;
+        const stored = applyEvent(session, event);
+        const key = InProcessSessionService.key(session.appName, session.userId, session.id);
+        const held = this.sessions.get(key);
+        if (held)
+            applyEvent(held, structuredClone(stored));
+        else
+            this.sessions.set(key, structuredClone(session));
+        return stored;
+    }
+}

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

@@ -25,9 +25,25 @@
  * subagents, nested syndicates), an optional deadline bounds wall-clock
  * time, and an outer AbortSignal cancels it. All three abort the provider
  * request in flight, not just the loop around it.
+ *
+ * ── Runtimes (ADR 0045, ADR 0073) ─────────────────────────────────────────
+ * Each agent of a turn runs on ADK's Runner (the default) or on the
+ * engine's own agent loop: the turn's `runtime` option, else
+ * MELCHIZEDEK_RUNTIME. Both compile the same AgentSpec (lib/compile.ts),
+ * store the same events and drain through drainAgentStream, so everything
+ * else here is shared. What native does not run yet fails before any model
+ * call, naming the feature (lib/runtime/nativeTurn.ts).
  */
 import type { BasePlugin } from '@google/adk';
 import type { BaseMemoryService, BaseSessionService, Event, LlmAgent } from '@google/adk';
+import type { RuntimeName } from './runtimeFlag.ts';
+import type { ToolCredentials } from '../tools/oauthConsent.ts';
+import type { PendingConsent } from './credentials.ts';
+export { CREDENTIAL_REQUEST, credentialResponsePart, describeConsent, pendingConsent } from './credentials.ts';
+export type { PendingConsent } from './credentials.ts';
+export type { ToolCredentials } from '../tools/oauthConsent.ts';
+export { chooseRuntime, runtimeSetting, DEFAULT_RUNTIME, RUNTIMES, UnsupportedOnRuntimeError } from './runtimeFlag.ts';
+export type { RuntimeName } from './runtimeFlag.ts';
 import type { PendingInput } from '../workflow.ts';
 export { describeInput } from '../workflow.ts';
 export type { PendingInput } from '../workflow.ts';
@@ -93,8 +109,15 @@ export interface SyndicateTurnOptions {
     memoryService?: BaseMemoryService;
     /** Model resolution, unknown-tool handling, nested loading. */
     compile?: CompileOptions;
-    /** Applied to every compiled agent before it runs (eval tool replay). */
+    /** Applied to every compiled agent before it runs (eval tool replay). ADK runtime only. */
     transformAgent?: (agent: LlmAgent) => LlmAgent;
+    /**
+     * The runtime that runs the turn's agents: `adk` (Google ADK's Runner) or
+     * `native` (the engine's own loop). Default: MELCHIZEDEK_RUNTIME, else
+     * `adk`. A feature native does not run yet throws UnsupportedOnRuntimeError
+     * before any model call.
+     */
+    runtime?: RuntimeName;
     /** Plan-dispatch only: skip the classifier and run this route. Overrides
      *  in the YAML still win, as they do in production. */
     forceRoute?: string;
@@ -109,6 +132,15 @@ export interface SyndicateTurnOptions {
     /** Root-span metadata; `false` disables tracing for the turn. */
     trace?: TraceOptions | false;
     events?: TurnEvents;
+    /**
+     * The turn's tool credentials (ADR 0072) and consent step (ADR 0085), on
+     * the native runtime. The store is pinned to `appName`; a tool reads the
+     * grant of `userId` only. With `consent`, a call whose provider the user
+     * has not granted pauses the turn input-required (`result.consent`), and
+     * the next message after the grant resumes it. Omitted: tools have no
+     * `accessToken`, as before.
+     */
+    toolCredentials?: ToolCredentials;
 }
 /** What one agent's event stream amounted to. */
 export interface DrainedRun {
@@ -159,8 +191,9 @@ export interface DrainedRun {
 export type TurnStage = 'classify' | 'dispatch' | 'delegate' | 'workflow';
 export interface RouteDecision extends RouteResolution {
     /** `approval`: the turn resumed the route that asked for an approval (ADR 0028).
-     *  `answer`: the message answered the route's open `ask_user` question. */
-    decidedBy: 'override' | 'forced' | 'classifier' | 'approval' | 'answer';
+     *  `answer`: the message answered the route's open `ask_user` question.
+     *  `consent`: the turn resumed the route whose call waited for an OAuth grant (ADR 0085). */
+    decidedBy: 'override' | 'forced' | 'classifier' | 'approval' | 'answer' | 'consent';
 }
 export interface SyndicateTurnResult {
     /** completed: an answer was produced. failed: an error, a deadline or the
@@ -173,6 +206,10 @@ export interface SyndicateTurnResult {
     /** The question a workflow's `ask_user` node asked, when status is
      *  input-required. The next message on the conversation is the answer. */
     input?: PendingInput;
+    /** The OAuth grant a paused call waits for, when status is input-required
+     *  (ADR 0085): the person opens `consent.authUri`; their next message after
+     *  the grant is stored resumes the call. */
+    consent?: PendingConsent;
     /** The text the user receives (relay fallback and guards applied). */
     text: string;
     error?: {
@@ -207,8 +244,7 @@ export interface TurnUsage {
     outputTokens: number;
     thinkingTokens: number;
 }
-export declare const DEFAULT_MODEL_ERROR_RETRIES = 2;
-export declare const DEFAULT_TOOL_ERROR_RETRIES = 3;
+export { DEFAULT_MODEL_ERROR_RETRIES, DEFAULT_TOOL_ERROR_RETRIES } from './native/selfCorrection.ts';
 /**
  * ADK's reflect-and-retry plugins, on by default. The model plugin turns a
  * reply ADK marks malformed (MALFORMED_FUNCTION_CALL) into a retry with