melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/runtime/native/interrupts.js

@@ -0,0 +1,291 @@
+/**
+ * lib/runtime/native/interrupts.ts — approvals on the native loop: the
+ * answer to an `adk_request_confirmation` call runs or refuses the pinned
+ * call before the next model step (WS2-7a, ADR 0028, ADR 0077).
+ *
+ * WHY this file exists:
+ *   A tool that requires approval does not run when called. The loop
+ *   (agentLoop.ts) stores ADK's `adk_request_confirmation` call in place of
+ *   the response, pinning the original call and its arguments, and the run
+ *   ends paused. The person's answer arrives as the next user message: a
+ *   function response to that call carrying `{ confirmed }`. On the ADK
+ *   runtime, LlmAgent's request-confirmation processor reads it before every
+ *   model step and runs the pinned call with the confirmation. This file is
+ *   that processor, case for case, so an approval opened on either runtime
+ *   resumes on the other and both store the same events.
+ *
+ * BEFORE EACH STEP, AS ADK'S PROCESSOR RUNS IT:
+ *   1. The answers: the function responses named `adk_request_confirmation`
+ *      in the latest user event (events on another branch left out), each
+ *      read as `{ confirmed, hint, payload }`, or as JSON under `response`.
+ *      None: nothing happens, and the step goes on as usual.
+ *   2. The gates they answer: every `adk_request_confirmation` call whose id
+ *      an answer names. A request authored by the user is refused
+ *      (`untrusted_request`); one authored by another agent is skipped; one
+ *      whose pinned call has no id or name is refused (`malformed_request`);
+ *      one this agent has already answered the pinned call after is skipped,
+ *      so a later step never runs the call again.
+ *   3. The binding. The pinned call must be one this agent made, by id
+ *      (`unknown_original_call`); its tool must be the agent's
+ *      (`unregistered_tool`); the name and the arguments must equal the
+ *      call's as the model made it (`tool_name_mismatch`,
+ *      `arguments_mismatch`); and the tool must require approval, or have
+ *      asked for it (`confirmation_not_required`). A refusal throws ADK's
+ *      IntentMismatchError text and nothing runs.
+ *   4. The bound calls run through the loop's own call path with the
+ *      confirmation in their context: an approved call runs its tool, a
+ *      refused one answers ADK's refusal. Their response is stored as its
+ *      own event before the step builds its request, so the model reads it.
+ *
+ * Not here: a plain-text "yes" as an answer (ADK's plainTextToolConfirmation,
+ * which no surface turns on), and answers delivered by a remote peer (ADK's
+ * remoteDelivered, which no surface sets).
+ *
+ * QUESTIONS (ask_user, WS2-7b, ADR 0079) need no processor here. ADK runs its
+ * request-input processor (REQUEST_INPUT_LLM_REQUEST_PROCESSOR) next, before
+ * compaction, but it only re-runs a node tool (a workflow run as a tool) that
+ * paused on an `adk_request_input` call; for an agent that lists no node tool
+ * it returns before doing anything, and no native agent lists one (native
+ * refuses workflows). An `ask_user` call is an ordinary long-running call:
+ * the turn runner stores the person's next message as its function response
+ * (lib/runtime/questions.ts questionAnswerPart), and the step reads the call
+ * and the answer side by side from the history (history.ts), as ADK's
+ * content processor does. When workflows run natively (WS4), the node-tool
+ * resume is ported beside approvedCalls, in the same place in the order.
+ *
+ * CREDENTIALS (OAuth consent, WS6-3b, ADR 0085) run first, as ADK runs its
+ * auth preprocessor (AUTH_PREPROCESSOR) before request-confirmation.
+ * grantedCalls is that preprocessor, check for check, with one difference
+ * in what the answer carries:
+ *   1. The answers: the function responses named `adk_request_credential`
+ *      in the last event with content, which must be the user's. None:
+ *      nothing happens.
+ *   2. The requests they answer: `adk_request_credential` calls this agent
+ *      made, by id. An answer naming no such request is ignored, as ADK
+ *      ignores it.
+ *   3. The binding. ADK's answer carries the authorization response (a code
+ *      or the redirect URL), which ADK exchanges in-process with the client
+ *      secret its request event stored. Here the server's callback route has
+ *      already exchanged the code and stored the grant
+ *      (lib/tools/oauthConsent.ts), so the answer carries no credential:
+ *      `{ credentialKey, granted: true }`, bound to the request by its
+ *      credentialKey. An answer that does not bind is ignored.
+ *   4. The paused calls the bound requests name (`function_call_id`, ADK's
+ *      toolset requests aside) run again, from the latest event that made
+ *      them, through the loop's own call path. The tool now reads its grant
+ *      through ctx.accessToken. The response is stored before the step
+ *      builds its request. A later step finds the agent's own events last,
+ *      so the call runs once.
+ *
+ * ADK stays out of this file: an ADK tool an agent still lists is asked
+ * whether it gates through its own checkRequireConfirmation, by shape.
+ */
+import { isDeepStrictEqual } from 'node:util';
+import { nativeToolOf } from '../../models/schemaNormalize.js';
+import { instructionToolOf, isTool, toolOf } from '../../tools/tool.js';
+import { getFunctionCalls, getFunctionResponses } from '../events.js';
+import { REQUEST_CONFIRMATION_CALL, REQUEST_CREDENTIAL_CALL, isSegmentPrefix } from './history.js';
+import { isToolset } from './request.js';
+/** A confirmation that does not bind to its pinned call: ADK's IntentMismatchError, by name and text. */
+export class IntentMismatchError extends Error {
+    reason;
+    functionCallId;
+    constructor(reason, functionCallId) {
+        super(`Tool confirmation rejected${functionCallId ? ` for function call '${functionCallId}'` : ''}: ${reason}.`);
+        this.name = 'IntentMismatchError';
+        this.reason = reason;
+        if (functionCallId !== undefined)
+            this.functionCallId = functionCallId;
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** ADK's parseToolConfirmation: `{ confirmed, hint, payload }`, or the same as JSON under `response`. */
+function parseConfirmation(response) {
+    const keys = Object.keys(response);
+    const fields = (keys.length === 1 && keys[0] === 'response' ? JSON.parse(String(response.response)) : response);
+    return { hint: typeof fields.hint === 'string' ? fields.hint : '', confirmed: fields.confirmed === true, payload: fields.payload };
+}
+/** Step 1: the answers in the latest user event, by the request id each names. */
+function answersIn(events) {
+    const answers = new Map();
+    let latest;
+    for (let i = events.length - 1; i >= 0 && !latest; i--)
+        if (events[i]?.author === 'user')
+            latest = events[i];
+    if (!latest)
+        return answers;
+    for (const r of getFunctionResponses(latest)) {
+        if (r.name !== REQUEST_CONFIRMATION_CALL || !r.id || !r.response)
+            continue;
+        answers.set(r.id, parseConfirmation(r.response));
+    }
+    return answers;
+}
+/** The agent's callable tools by name, toolsets expanded, as ADK's canonicalTools lists them. */
+async function toolsOf(agent, scope) {
+    const state = scope.session.state;
+    const toolsetContext = {
+        agentName: agent.name,
+        invocationId: scope.invocationId,
+        state: { get: (key) => state[key], has: (key) => Object.hasOwn(state, key) },
+    };
+    const tools = new Map();
+    for (const union of agent.tools ?? []) {
+        const expanded = isToolset(union) ? await union.getTools(toolsetContext) : [union];
+        for (const listed of expanded) {
+            if (nativeToolOf(listed) || instructionToolOf(listed))
+                continue;
+            const name = listed?.name;
+            if (typeof name === 'string')
+                tools.set(name, toolOf(listed) ?? listed);
+        }
+    }
+    return tools;
+}
+/** Whether `tool` gates the call: an own Tool's requiresApproval, an ADK tool's checkRequireConfirmation. */
+async function gates(tool, args, context) {
+    if (isTool(tool))
+        return tool.requiresApproval === true;
+    const check = tool.checkRequireConfirmation;
+    return typeof check === 'function' ? (await check.call(tool, args, context)) === true : false;
+}
+/**
+ * The pinned calls the latest user message approves or refuses, bound to
+ * the calls this agent made; undefined when it answers no open request.
+ * Throws IntentMismatchError when an answer does not bind (nothing runs).
+ * `contextFor` makes the context a tool's gate check reads.
+ */
+export async function approvedCalls(agent, scope, contextFor) {
+    const all = scope.session.events;
+    const events = scope.branch ? all.filter((e) => !e.branch || isSegmentPrefix(scope.branch, e.branch)) : all;
+    if (events.length === 0)
+        return undefined;
+    const answers = answersIn(events);
+    if (answers.size === 0)
+        return undefined;
+    // Step 2: the gates the answers name.
+    const candidates = [];
+    for (const [index, event] of events.entries()) {
+        for (const call of getFunctionCalls(event)) {
+            const confirmation = call.id ? answers.get(call.id) : undefined;
+            if (!confirmation || call.name !== REQUEST_CONFIRMATION_CALL)
+                continue;
+            if (event.author !== agent.name) {
+                if (event.author === 'user')
+                    throw new IntentMismatchError('untrusted_request', call.id);
+                continue;
+            }
+            const pinned = isRecord(call.args) ? call.args.originalFunctionCall : undefined;
+            if (!isRecord(pinned))
+                continue;
+            if (!pinned.id || !pinned.name)
+                throw new IntentMismatchError('malformed_request', call.id);
+            const pinnedCall = pinned;
+            const answeredAfter = events
+                .slice(index + 1)
+                .some((e) => e.author === agent.name && getFunctionResponses(e).some((r) => r.id === pinnedCall.id));
+            if (!answeredAfter)
+                candidates.push({ pinned: pinnedCall, confirmation });
+        }
+    }
+    if (candidates.length === 0)
+        return undefined;
+    // Step 3: each pinned call bound to the call the agent made, by id, name and arguments.
+    const tools = await toolsOf(agent, scope);
+    const made = new Map();
+    const requested = new Set();
+    for (const event of events) {
+        if (event.author !== agent.name)
+            continue;
+        for (const call of getFunctionCalls(event))
+            if (call.id && call.name !== REQUEST_CONFIRMATION_CALL)
+                made.set(call.id, call);
+        for (const id of Object.keys(event.actions?.requestedToolConfirmations ?? {}))
+            requested.add(id);
+    }
+    const bound = new Map();
+    for (const { pinned, confirmation } of candidates) {
+        const id = pinned.id;
+        const original = made.get(id);
+        if (!original)
+            throw new IntentMismatchError('unknown_original_call', id);
+        const tool = tools.get(pinned.name);
+        if (!tool)
+            throw new IntentMismatchError('unregistered_tool', id);
+        if (original.name !== pinned.name)
+            throw new IntentMismatchError('tool_name_mismatch', id);
+        if (!isDeepStrictEqual(original.args ?? {}, pinned.args ?? {}))
+            throw new IntentMismatchError('arguments_mismatch', id);
+        if (!(await gates(tool, original.args ?? {}, contextFor(id))) && !requested.has(id))
+            throw new IntentMismatchError('confirmation_not_required', id);
+        bound.set(id, { call: pinned, confirmation });
+    }
+    return {
+        calls: [...bound.values()].map((b) => b.call),
+        confirmations: new Map([...bound].map(([id, b]) => [id, b.confirmation])),
+        tools,
+    };
+}
+// ── Credentials (ADK's auth preprocessor) ────────────────────────────────────
+/** ADK's prefix for a toolset's own credential request, which resumes no call. */
+const TOOLSET_AUTH_CREDENTIAL_ID_PREFIX = '_adk_toolset_auth_';
+/** Whether an answer binds to the request it names: granted, for the provider the request named. */
+function bindsGrant(config, response) {
+    if (!isRecord(response) || response.granted !== true)
+        return false;
+    return typeof config.credentialKey === 'string' && config.credentialKey !== '' && response.credentialKey === config.credentialKey;
+}
+/**
+ * The paused calls the latest user message resumes by answering this
+ * agent's credential requests; undefined when it answers none (ADK's
+ * AuthPreprocessor, the exchange left to the callback route).
+ */
+export async function grantedCalls(agent, scope) {
+    const events = scope.session.events;
+    if (events.length === 0)
+        return undefined;
+    let last;
+    for (let i = events.length - 1; i >= 0 && !last; i--)
+        if (events[i]?.content !== undefined)
+            last = events[i];
+    if (!last || last.author !== 'user')
+        return undefined;
+    const answers = new Map();
+    for (const r of getFunctionResponses(last))
+        if (r.name === REQUEST_CREDENTIAL_CALL && r.id)
+            answers.set(r.id, r.response);
+    if (answers.size === 0)
+        return undefined;
+    // The requests this agent made, by id.
+    const requests = new Map();
+    for (const event of events) {
+        if (event.author !== agent.name)
+            continue;
+        for (const call of getFunctionCalls(event)) {
+            if (!call.id || !answers.has(call.id) || call.name !== REQUEST_CREDENTIAL_CALL || !isRecord(call.args))
+                continue;
+            const config = call.args.auth_config ?? call.args.authConfig;
+            if (isRecord(config))
+                requests.set(call.id, { config, args: call.args });
+        }
+    }
+    const resume = new Set();
+    for (const [id, response] of answers) {
+        const request = requests.get(id);
+        if (!request || !bindsGrant(request.config, response))
+            continue;
+        const callId = request.args.function_call_id ?? request.args.functionCallId;
+        if (typeof callId === 'string' && callId && !callId.startsWith(TOOLSET_AUTH_CREDENTIAL_ID_PREFIX))
+            resume.add(callId);
+    }
+    if (resume.size === 0)
+        return undefined;
+    // As ADK: the latest event before the answer that made any of the calls, those calls only.
+    for (let i = events.length - 2; i >= 0; i--) {
+        const calls = getFunctionCalls(events[i]);
+        if (!calls.some((c) => c.id && resume.has(c.id)))
+            continue;
+        return { calls: calls.filter((c) => c.id && resume.has(c.id)), tools: await toolsOf(agent, scope) };
+    }
+    return undefined;
+}

package/dist/lib/runtime/native/request.d.ts

@@ -0,0 +1,215 @@
+/**
+ * lib/runtime/native/request.ts — one model request of the native loop,
+ * built from an agent and its session (ADR 0045, ADR 0066).
+ *
+ * WHY this file exists:
+ *   The native runtime calls a ModelAdapter (lib/models/contract.ts) with a
+ *   ModelRequest it builds itself, with no LlmRequest in between. A session
+ *   moves between the runtimes and an agent must behave the same on either,
+ *   so the request is the one the ADK runtime hands the same adapter for
+ *   the same agent and session: what ADK's LlmAgent request processors and
+ *   tools build, read through the shim's mapping (llmRequestToModelRequest,
+ *   lib/models/genaiMapping.ts). tests/nativeStep.test.ts asserts that on
+ *   whole syndicates.
+ *
+ * THE REQUEST, in the order ADK builds it:
+ *   1. The agent's generateContentConfig, and its output schema when it has
+ *      no tools (or the model takes a schema beside tools: Gemini 2 and
+ *      later on Vertex AI).
+ *   2. The system prompt, each piece joined to the last by a blank line:
+ *      - the identity lines ("You are an agent. Your internal name is …"),
+ *        unless the agent may transfer to no one (an output schema rules
+ *        transfer out);
+ *      - the root agent's globalInstruction, then the agent's instruction,
+ *        each with `{state_key}` placeholders filled from session state,
+ *        and, in a workflow node's run, `{input.field}` and
+ *        `<input.field from Node>` filled from its workflow scope;
+ *      - with an output schema beside tools on a model that cannot take
+ *        both, the line asking for set_model_response;
+ *      - then, at each tool's place in the agent's list, the text its
+ *        `instruction(ctx)` writes: few-shot examples, preload_memory, an
+ *        own Tool's note (ADR 0059, ADR 0062). The skills index is part of
+ *        the instruction itself (lib/compile.ts appends it).
+ *      A Tool's `contents` hook then adds to the history, after it is
+ *      projected (load_skill_resource's binary file, ADR 0083).
+ *   3. The history: the session's events projected by includeContents
+ *      (lib/runtime/native/history.ts), with Gemini code execution's parts
+ *      as text when the agent runs code.
+ *   4. The tools, in the agent's order, a toolset expanded to its tools:
+ *      each client-side tool's declaration (contractToolDeclaration), at
+ *      most one per name, the later one winning; each server-side tool
+ *      where the ADK runtime sends it (web_search everywhere, url_context
+ *      and google_search on Gemini, x_search and collections_search on
+ *      xAI); `code_execution` first among Gemini's own tools; and the
+ *      set_model_response tool when (2) asked for it, then the caller's
+ *      `extraTools` (self-correction's reflection tool, as ADK's plugin adds
+ *      it to the toolsDict last). In `mode: task`, finish_task takes
+ *      set_model_response's place and the output schema is never the
+ *      response schema (lib/runtime/native/taskMode.ts).
+ *   5. Tool choice, the output schema or JSON mode, reasoning and sampling,
+ *      read from the config by the mapping's own readers.
+ *
+ * WHAT IT DOES NOT DO (later tickets): resume an approval or an input
+ * request (ADK's confirmation and input processors run tools before the
+ * request; WS2-7), add transfer_to_agent
+ * (compiled syndicates never set subAgents; they delegate through subagent tools, delegate.ts),
+ * artifacts in an
+ * instruction (no runtime has an artifact service), and an ADK tool's own
+ * processLlmRequest side effects beyond its declaration (an own Tool says
+ * what it writes through `instruction`).
+ *
+ * ADK STAYS OUT OF THIS FILE'S OWN LOGIC: it reads tools by marker and by
+ * the own-tool symbols (lib/tools/tool.ts), and only lib/models/
+ * genaiMapping.ts, which stored history needs anyway (ADR 0048 item 8),
+ * names @google/*. An ADK tool or toolset an agent still carries (an
+ * AgentTool, an MCP or OpenAPI tool) is read through its declaration and
+ * `getTools`, by shape, as is the engine's own skills toolset.
+ */
+import type { ModelRequest } from '../../models/contract.ts';
+import type { MemoryService } from '../memoryService.ts';
+import type { TurnContent, TurnEvent } from '../events.ts';
+import type { Session } from '../sessions.ts';
+import type { Tool } from '../../tools/tool.ts';
+import type { ContextConfig } from './compaction.ts';
+/**
+ * One agent as the native loop runs it: the fields of a compiled agent that
+ * shape its model requests, in the YAML's own spelling. lib/compile.ts
+ * builds the same fields into ADK's LlmAgent, and lib/compileNative.ts
+ * builds this from the same AgentSpec (ADR 0073).
+ */
+export interface NativeAgent {
+    name: string;
+    description?: string;
+    /** The model id, as the YAML names it. */
+    model: string;
+    /**
+     * The agent's instruction. A string has `{key}` placeholders filled from
+     * session state (`{key?}` is optional); a function's result is used as it is.
+     */
+    instruction?: string | ((ctx: InstructionContext) => string | Promise<string>);
+    /** Prepended to every request of the run's root agent (ADK's global instruction). */
+    globalInstruction?: string | ((ctx: InstructionContext) => string | Promise<string>);
+    /**
+     * In the agent's order: own Tools and defineTool contracts, InstructionTools,
+     * NativeToolMarkers, and during the dual period the ADK tools and toolsets
+     * an agent may still list (their own-tool symbols are read first).
+     */
+    tools?: readonly unknown[];
+    /** The answer's schema, as the YAML spells it (lowercase or Gemini's dialect). */
+    outputSchema?: Record<string, unknown>;
+    /** As lib/compile.ts builds it: the YAML's config with `reasoning:` mapped in (withReasoning). */
+    generateContentConfig?: Record<string, unknown>;
+    includeContents?: 'default' | 'none';
+    disallowTransferToParent?: boolean;
+    disallowTransferToPeers?: boolean;
+    /** `code_execution: gemini`: Gemini runs the code it writes. */
+    codeExecution?: 'gemini';
+    /** `mode: task` (workflow nodes): finish_task is declared after the agent's tools and the output schema is its parameters (lib/runtime/native/taskMode.ts). */
+    mode?: 'task';
+    /** The session-state key the agent's final answer is saved under (the loop writes it, lib/runtime/native/agentLoop.ts). */
+    outputKey?: string;
+    /** `fallback_model:`: answers a provider-side failure of the agent's model (ADR 0044). The loop calls it as its own leaf adapter. */
+    fallbackModel?: string;
+    /** `context:` (ADR 0033): compact the history into a summary past a token threshold. The loop runs it before each step (compaction.ts). */
+    context?: ContextConfig;
+}
+/** What an instruction function reads. */
+export interface InstructionContext {
+    readonly agentName: string;
+    readonly invocationId: string;
+    readonly state: Readonly<Record<string, unknown>>;
+    readonly userContent?: TurnContent;
+}
+/** Where the request is made: the run, its session, and who it is for. */
+export interface RequestContext {
+    /** The session as it stands: the run's user event already appended. */
+    session: Session;
+    invocationId: string;
+    /** The message that started the run (the examples block reads it). */
+    userContent?: TurnContent;
+    /** The run's branch; undefined at the root. */
+    branch?: string;
+    isolationScope?: string;
+    /** The run's root agent, whose globalInstruction applies. Default: the agent itself. */
+    root?: Pick<NativeAgent, 'globalInstruction'>;
+    /** The run's memory, already namespaced: preload_memory and load_memory read it. */
+    memory?: Pick<MemoryService, 'search'>;
+    /** Stream text and thinking as partial responses. Default false. */
+    stream?: boolean;
+    /**
+     * State laid over the session's for this request: the run's `temp:` keys,
+     * which no store keeps (lib/runtime/native/tempState.ts).
+     */
+    stateOverlay?: Readonly<Record<string, unknown>>;
+    /** Aborts the call in flight: the turn's signal. */
+    signal?: AbortSignal;
+    /**
+     * Tools declared after the agent's own, as a plugin's beforeModelCallback
+     * adds them to ADK's toolsDict last: self-correction's reflection tool
+     * (lib/runtime/native/selfCorrection.ts).
+     */
+    extraTools?: readonly unknown[];
+    /**
+     * A workflow agent node's run: the node's input and the outputs stored so
+     * far, which fill the instruction's workflow placeholders as ADK's
+     * workflowInstructionScope does (lib/workflow/agentNode.ts).
+     */
+    workflowScope?: WorkflowInstructionScope;
+}
+/** A request, and the client-side tools it declares by name (what the loop runs and checks for long-running calls). */
+export interface BuiltRequest {
+    request: ModelRequest;
+    /** By declared name, in the request's order: the own Tool when there is one, else the object listed. */
+    tools: Map<string, unknown>;
+}
+/** The tool ADK adds when an agent has an output schema and tools a model cannot take together. */
+export declare const SET_MODEL_RESPONSE = "set_model_response";
+/** set_model_response as an own Tool: its answer is the arguments, as JSON text, and it ends the step. */
+export declare function setModelResponseTool(outputSchema: Record<string, unknown>): Tool;
+/** Whether the model takes an output schema beside tools in one request (ADK: Vertex AI, Gemini 2 and later). */
+export declare function outputSchemaWithTools(model: string): boolean;
+/**
+ * What ADK's runLlmAgentAsNode puts in a node agent's invocation context
+ * (`withWorkflowInstructionScope`): the node's input, and the output each
+ * node of the invocation stored so far, by node name, the last one winning.
+ * Its instruction then fills `{<any>.<field>}` from the input and
+ * `<<any>.<field> from <Node>>` from that node's output.
+ */
+export interface WorkflowInstructionScope {
+    readonly input: unknown;
+    readonly outputsByNode: Readonly<Record<string, unknown>>;
+}
+/**
+ * ADK's collectPredecessorOutputs: the output every event of the invocation
+ * carries, keyed by the last segment of its node path without the run
+ * suffix (`Graph.Fan.Agent@2` is `Agent`), the later event winning.
+ */
+export declare function predecessorOutputs(events: readonly TurnEvent[], invocationId: string): Record<string, unknown>;
+/**
+ * `template` with each `{key}` naming a state key replaced by the value in
+ * `state` (a string as it is, anything else as JSON). `{key?}` is optional
+ * and becomes empty when the key is absent; a required key that is absent
+ * fails, as on the ADK runtime. A placeholder that names no state key
+ * (`{ "a": 1 }` in an example) stays as it is. `{artifact.x}` fails: no
+ * runtime of this engine has an artifact service. Own keys only: a key such
+ * as `constructor` is absent unless the state holds it.
+ *
+ * With a workflow `scope` (a workflow agent node's run), ADK 2.2's two
+ * workflow placeholders are filled too, as its injectSessionState fills
+ * them: `{x.field}` (any identifier before the dot) from the node's input
+ * when it is an object holding `field`, `''` when optional and absent, else
+ * left as written (the key's first spelling); and `<x.field from Node>`
+ * from that node's stored object output, else left as written.
+ */
+export declare function injectSessionState(template: string, state: Readonly<Record<string, unknown>>, scope?: WorkflowInstructionScope): string;
+/** A toolset (the skills harness, an MCP toolset): something that yields tools, and is not one. */
+export declare function isToolset(value: unknown): value is {
+    getTools(ctx?: unknown): Promise<unknown[]>;
+};
+/**
+ * The ModelRequest the native loop sends for `agent` now, with the
+ * client-side tools it declares. Throws where the ADK runtime throws
+ * building the same request: a required state key that is absent, a
+ * Gemini-only tool on another model, a config field LlmAgent refuses.
+ */
+export declare function buildModelRequest(agent: NativeAgent, ctx: RequestContext): Promise<BuiltRequest>;