melchizedek-agents 0.18.0 → 0.19.0

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

@@ -0,0 +1,585 @@
+/**
+ * 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 { contentsToMessages, reasoningOf, samplingOf, systemText, toolChoiceOf } from '../../models/genaiMapping.js';
+import { providerForModel } from '../../models/providerMap.js';
+import { contractToolDeclaration, nativeToolOf, toContractJsonSchema } from '../../models/schemaNormalize.js';
+import { createToolContext, instructionToolOf, isTool, toolOf } from '../../tools/tool.js';
+import { convertCodeExecutionParts, projectHistory } from './history.js';
+import { finishTaskTool } from './taskMode.js';
+import { withStateOverlay } from './tempState.js';
+// ── set_model_response (ADK's output schema beside tools) ────────────────────
+/** The tool ADK adds when an agent has an output schema and tools a model cannot take together. */
+export const SET_MODEL_RESPONSE = 'set_model_response';
+const SET_MODEL_RESPONSE_DESCRIPTION = 'Call this tool to submit your final response conforming to the output schema. Use this tool only when you have collected all the information and are ready to return the final answer.';
+const SET_MODEL_RESPONSE_INSTRUCTION = 'To output the final result, you must call the "set_model_response" function with the appropriate values. Do not output anything else.';
+/** set_model_response as an own Tool: its answer is the arguments, as JSON text, and it ends the step. */
+export function setModelResponseTool(outputSchema) {
+    return {
+        name: SET_MODEL_RESPONSE,
+        declaration: () => ({
+            name: SET_MODEL_RESPONSE,
+            description: SET_MODEL_RESPONSE_DESCRIPTION,
+            parameters: toContractJsonSchema(outputSchema),
+        }),
+        execute: async (args, ctx) => {
+            ctx.actions.skipSummarization = true;
+            return JSON.stringify(args);
+        },
+    };
+}
+// ── Model names (ADK's utils/model_name.js and output_schema_utils.js) ───────
+/** A Vertex AI resource name's model id, else the id itself. Split, never a backtracking pattern. */
+function modelName(model) {
+    const parts = model.split('/');
+    const isResource = parts.length >= 8 &&
+        parts[0] === 'projects' &&
+        parts[2] === 'locations' &&
+        parts[4] === 'publishers' &&
+        parts[6] === 'models' &&
+        [1, 3, 5].every((i) => (parts[i] ?? '') !== '');
+    if (!isResource)
+        return model;
+    const rest = parts.slice(7).join('/');
+    return rest === '' ? model : rest;
+}
+function isGeminiModel(model) {
+    return modelName(model).startsWith('gemini-');
+}
+function isGemini1Model(model) {
+    return modelName(model).startsWith('gemini-1');
+}
+function isGemini2OrAbove(model) {
+    const name = modelName(model);
+    if (!name.startsWith('gemini-'))
+        return false;
+    const version = name.slice('gemini-'.length).split('-', 1)[0] ?? '';
+    if (!/^\d+(\.\d+)*$/.test(version))
+        return false;
+    return Number.parseInt(version, 10) >= 2;
+}
+function envFlag(name) {
+    return ['true', '1'].includes((process.env[name] || '').toLowerCase());
+}
+/** ADK's enterprise switch: GOOGLE_GENAI_USE_ENTERPRISE, else the deprecated GOOGLE_GENAI_USE_VERTEXAI. */
+function vertexAi() {
+    if (process.env.GOOGLE_GENAI_USE_ENTERPRISE !== undefined)
+        return envFlag('GOOGLE_GENAI_USE_ENTERPRISE');
+    return envFlag('GOOGLE_GENAI_USE_VERTEXAI');
+}
+/** Whether the model takes an output schema beside tools in one request (ADK: Vertex AI, Gemini 2 and later). */
+export function outputSchemaWithTools(model) {
+    return vertexAi() && isGemini2OrAbove(model);
+}
+// ── Session state in an instruction (ADK's injectSessionState) ───────────────
+const STATE_PREFIXES = ['app:', 'user:', 'temp:'];
+const ARTIFACT_PREFIX = 'artifact.';
+function isIdentifier(s) {
+    return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(s);
+}
+function isStateName(name) {
+    const parts = name.split(':');
+    if (parts.length === 1)
+        return isIdentifier(name);
+    if (parts.length !== 2)
+        return false;
+    return STATE_PREFIXES.includes(`${parts[0]}:`) && isIdentifier(parts[1]);
+}
+/**
+ * Every `{…}` placeholder in a template, as ADK's `/\{+[^{}]*}+/g` finds
+ * them, by one linear scan (the regular expression backtracks on a long run
+ * of braces): a run of `{`, then no brace, then a run of `}`.
+ */
+function placeholders(template) {
+    const found = [];
+    let i = 0;
+    while (i < template.length) {
+        const open = template.indexOf('{', i);
+        if (open < 0)
+            break;
+        let j = open;
+        while (template[j] === '{')
+            j++;
+        let k = j;
+        while (k < template.length && template[k] !== '{' && template[k] !== '}')
+            k++;
+        if (template[k] !== '}') {
+            i = k;
+            continue;
+        }
+        let end = k;
+        while (template[end] === '}')
+            end++;
+        found.push({ raw: template.slice(open, end), index: open });
+        i = end;
+    }
+    return found;
+}
+const isWordChar = (c) => c !== undefined && ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c === '_');
+const isIdentStart = (c) => c !== undefined && c !== '' && isWordChar(c) && !(c >= '0' && c <= '9');
+const isSpace = (c) => c !== undefined && c !== '' && /\s/.test(c);
+/** ADK's WORKFLOW_FIELD_KEY, `^[A-Za-z_]\w*\.[A-Za-z_]\w*$`, without a pattern: two identifiers joined by one dot. */
+function isWorkflowFieldKey(key) {
+    const dot = key.indexOf('.');
+    return dot > 0 && isIdentifier(key.slice(0, dot)) && isIdentifier(key.slice(dot + 1));
+}
+/** The identifier `[A-Za-z_]\w*` starting at `i`, and where it ends; undefined when none starts there. */
+function identAt(s, i) {
+    if (!isIdentStart(s[i]))
+        return undefined;
+    let end = i + 1;
+    while (isWordChar(s[end]))
+        end++;
+    return { name: s.slice(i, end), end };
+}
+function skipSpaces(s, i) {
+    while (isSpace(s[i]))
+        i++;
+    return i;
+}
+/**
+ * Every `<x.field from Node>` placeholder, as ADK's SOURCE_NODE_PLACEHOLDER,
+ * `/<\s*[A-Za-z_]\w*\.([A-Za-z_]\w*)\s+from\s+([A-Za-z_]\w*)\s*>/g`, finds
+ * them. Each token of that pattern is determined by the next character, so
+ * a hand parser takes the same matches; an attempt from a `<` cannot pass
+ * the next `<`, so the scan is linear.
+ */
+function sourcePlaceholders(template) {
+    const found = [];
+    let open = template.indexOf('<');
+    while (open >= 0) {
+        const match = sourcePlaceholderAt(template, open);
+        if (match)
+            found.push(match);
+        open = template.indexOf('<', match ? match.index + match.raw.length : open + 1);
+    }
+    return found;
+}
+function sourcePlaceholderAt(s, open) {
+    const head = identAt(s, skipSpaces(s, open + 1));
+    if (!head || s[head.end] !== '.')
+        return undefined;
+    const field = identAt(s, head.end + 1);
+    if (!field || !isSpace(s[field.end]))
+        return undefined;
+    const from = skipSpaces(s, field.end);
+    if (s.slice(from, from + 4) !== 'from' || !isSpace(s[from + 4]))
+        return undefined;
+    const node = identAt(s, skipSpaces(s, from + 4));
+    if (!node)
+        return undefined;
+    const close = skipSpaces(s, node.end);
+    if (s[close] !== '>')
+        return undefined;
+    return { raw: s.slice(open, close + 1), index: open, field: field.name, node: node.name };
+}
+/** ADK's resolveSourceNode: the field of the named node's object output, else the placeholder as written. */
+function resolveSourceNode(raw, field, node, scope) {
+    const out = scope.outputsByNode[node];
+    if (out && typeof out === 'object' && field in out)
+        return formatValue(out[field]);
+    return raw;
+}
+/**
+ * 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 function predecessorOutputs(events, invocationId) {
+    const outputs = {};
+    for (const event of events) {
+        if (event.invocationId !== invocationId || event.output === undefined)
+            continue;
+        const path = event.nodeInfo?.path;
+        if (!path)
+            continue;
+        const leaf = path.slice(path.lastIndexOf('.') + 1);
+        const at = leaf.indexOf('@');
+        outputs[at >= 0 ? leaf.slice(0, at) : leaf] = event.output;
+    }
+    return outputs;
+}
+function stripBraces(raw) {
+    let start = 0;
+    let end = raw.length;
+    while (start < end && raw[start] === '{')
+        start++;
+    while (end > start && raw[end - 1] === '}')
+        end--;
+    return raw.slice(start, end).trim();
+}
+function formatValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && value !== null) {
+        try {
+            const json = JSON.stringify(value);
+            if (json !== undefined)
+                return json;
+        }
+        catch (e) {
+            throw new Error(`Failed to serialize value for instruction template: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return String(value);
+}
+/**
+ * `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 function injectSessionState(template, state, scope) {
+    const sources = scope ? sourcePlaceholders(template).map((m) => ({ raw: m.raw, index: m.index, text: resolveSourceNode(m.raw, m.field, m.node, scope) })) : [];
+    const matches = placeholders(template);
+    if (matches.length === 0 && sources.length === 0)
+        return template;
+    const parsed = matches.map((m) => {
+        let key = stripBraces(m.raw);
+        const optional = key.endsWith('?');
+        if (optional)
+            key = key.slice(0, -1);
+        return { ...m, key, optional, valid: key.startsWith(ARTIFACT_PREFIX) || isStateName(key) || (!!scope && isWorkflowFieldKey(key)) };
+    });
+    const unique = new Map();
+    for (const p of parsed) {
+        if (!p.valid)
+            continue;
+        const seen = unique.get(p.key);
+        if (seen)
+            seen.required ||= !p.optional;
+        else
+            unique.set(p.key, { required: !p.optional, raw: p.raw });
+    }
+    const values = new Map();
+    for (const [key, { required, raw }] of unique)
+        values.set(key, resolveKey(key, required, raw, state, scope));
+    // ADK's merge: both kinds in template order, each replaced in turn.
+    const all = [...parsed.map((p) => ({ raw: p.raw, index: p.index, text: p.valid ? values.get(p.key) : p.raw })), ...sources].sort((a, b) => a.index - b.index);
+    let out = '';
+    let last = 0;
+    for (const p of all) {
+        out += template.slice(last, p.index) + p.text;
+        last = p.index + p.raw.length;
+    }
+    return out + template.slice(last);
+}
+/** ADK's resolveKey for one placeholder key: an artifact (refused), a state key, or a workflow field. */
+function resolveKey(key, required, raw, state, scope) {
+    if (key.startsWith(ARTIFACT_PREFIX))
+        throw new Error('Artifact service is not initialized.');
+    if (isStateName(key)) {
+        if (Object.hasOwn(state, key))
+            return formatValue(state[key]);
+        if (!required)
+            return '';
+        throw new Error(`Context variable not found: \`${key}\`.`);
+    }
+    if (scope && isWorkflowFieldKey(key)) {
+        const field = key.slice(key.indexOf('.') + 1);
+        const input = scope.input;
+        if (input && typeof input === 'object' && field in input)
+            return formatValue(input[field]);
+        if (!required)
+            return '';
+    }
+    return raw;
+}
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** ADK's appendInstructions: the texts joined by a blank line, after a blank line when there is text already. */
+function appendInstructions(system, texts) {
+    const added = texts.join('\n\n');
+    return system ? `${system}\n\n${added}` : added;
+}
+async function resolveInstruction(instruction, ctx, scope) {
+    if (typeof instruction === 'function')
+        return instruction(ctx);
+    return injectSessionState(instruction ?? '', ctx.state, scope);
+}
+/** A toolset (the skills harness, an MCP toolset): something that yields tools, and is not one. */
+export function isToolset(value) {
+    if (!isObject(value))
+        return false;
+    if (typeof value.getTools !== 'function')
+        return false;
+    return !('runAsync' in value) && !isTool(value) && typeof value._getDeclaration !== 'function';
+}
+/**
+ * `configTools`: how many entries Gemini's own tool list holds so far (its
+ * native tools, and one function-declarations entry per declared tool),
+ * which Gemini 1's search refuses to share.
+ */
+function placementOf(native, model, configTools) {
+    const provider = providerForModel(model);
+    switch (native) {
+        case 'web_search':
+            return provider === 'gemini' ? { in: 'config', as: 'web_search' } : { in: 'dict' };
+        case 'x_search':
+        case 'collections_search':
+            return provider === 'xai' ? { in: 'dict' } : { in: 'none' };
+        case 'url_context':
+            return provider === 'gemini' ? { in: 'config', as: 'url_context' } : { in: 'none' };
+        case 'google_search':
+            // ADK's own GoogleSearchTool: Gemini only, and alone on Gemini 1.
+            if (isGemini1Model(model)) {
+                if (configTools > 0)
+                    throw new Error('Google search tool can not be used with other tools in Gemini 1.x.');
+                return { in: 'config', as: 'web_search' };
+            }
+            if (isGeminiModel(model))
+                return { in: 'config', as: 'web_search' };
+            throw new Error(`Google search tool is not supported for model ${model}`);
+        case 'code_execution':
+            // The agent's code_execution: gemini, never a listed tool.
+            return { in: 'none' };
+    }
+}
+/**
+ * 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 async function buildModelRequest(agent, ctx) {
+    const model = agent.model;
+    const cfg = { ...(agent.generateContentConfig ?? {}) };
+    // LlmAgent's own refusals, so a config that cannot run under ADK cannot run here.
+    if (cfg.tools)
+        throw new Error('All tools must be set via LlmAgent.tools.');
+    if (cfg.systemInstruction)
+        throw new Error('System instruction must be set via LlmAgent.instruction.');
+    if (cfg.responseSchema)
+        throw new Error('Response schema must be set via LlmAgent.output_schema.');
+    const listed = agent.tools ?? [];
+    const taskMode = agent.mode === 'task';
+    const schemaWithTools = !!agent.outputSchema && listed.length > 0 && !outputSchemaWithTools(model);
+    // 1. Basic: the config, and the output schema where the model takes it (never in task mode: finish_task carries it).
+    if (agent.outputSchema && !schemaWithTools && !taskMode) {
+        cfg.responseSchema = agent.outputSchema;
+        cfg.responseMimeType = 'application/json';
+    }
+    const state = withStateOverlay(ctx.session.state, ctx.stateOverlay);
+    const instructionCtx = {
+        agentName: agent.name,
+        invocationId: ctx.invocationId,
+        state,
+        ...(ctx.userContent ? { userContent: ctx.userContent } : {}),
+    };
+    // 2. Identity, then the root's global instruction, then the agent's own.
+    let system;
+    const transferDisabled = !!agent.outputSchema || (agent.disallowTransferToParent === true && agent.disallowTransferToPeers === true);
+    if (!transferDisabled) {
+        const identity = [`You are an agent. Your internal name is "${agent.name}".`];
+        if (agent.description)
+            identity.push(`The description about you is "${agent.description}"`);
+        system = appendInstructions(system, identity);
+    }
+    const globalInstruction = (ctx.root ?? agent).globalInstruction;
+    if (globalInstruction)
+        system = appendInstructions(system, [await resolveInstruction(globalInstruction, instructionCtx, ctx.workflowScope)]);
+    if (agent.instruction)
+        system = appendInstructions(system, [await resolveInstruction(agent.instruction, instructionCtx, ctx.workflowScope)]);
+    if (schemaWithTools)
+        system = appendInstructions(system, [SET_MODEL_RESPONSE_INSTRUCTION]);
+    // 3. The history, and Gemini code execution's parts in it.
+    const contents = projectHistory(ctx.session.events, {
+        agentName: agent.name,
+        includeContents: agent.includeContents ?? 'default',
+        branch: ctx.branch,
+        isolationScope: ctx.isolationScope,
+    });
+    const configNatives = [];
+    if (agent.codeExecution === 'gemini') {
+        if (!isGemini2OrAbove(model))
+            throw new Error(`Gemini code execution tool is not supported for model ${model}`);
+        configNatives.push('code_execution');
+        for (const content of contents)
+            convertCodeExecutionParts(content);
+    }
+    // 4. The tools, in the agent's order.
+    const toolContext = createToolContext({
+        invocationId: ctx.invocationId,
+        agentName: agent.name,
+        userId: ctx.session.userId,
+        appName: ctx.session.appName,
+        sessionId: ctx.session.id,
+        state,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        ...(ctx.userContent ? { userContent: ctx.userContent } : {}),
+        ...(ctx.memory ? { memory: ctx.memory } : {}),
+    });
+    // What a toolset reads to list its tools (ADK's ReadonlyContext, by shape).
+    const toolsetContext = {
+        agentName: agent.name,
+        invocationId: ctx.invocationId,
+        state: { get: (key) => state[key], has: (key) => Object.hasOwn(state, key) },
+    };
+    const all = [...listed];
+    // Task mode (lib/runtime/native/taskMode.ts): finish_task in set_model_response's place. ADK's
+    // instruction processor still writes the set_model_response line above; LlmAgent adds no such tool.
+    if (taskMode)
+        all.push(finishTaskTool(agent.outputSchema));
+    else if (schemaWithTools)
+        all.push(setModelResponseTool(agent.outputSchema));
+    if (ctx.extraTools)
+        all.push(...ctx.extraTools);
+    // One entry per name, in first-listed order, the later object winning (ADK's toolsDict).
+    const dict = new Map();
+    const instructionTexts = [];
+    const contentWriters = [];
+    for (const union of all) {
+        const expanded = isToolset(union) ? await union.getTools(toolsetContext) : [union];
+        for (const listedTool of expanded) {
+            const native = nativeToolOf(listedTool);
+            if (native) {
+                const declaredSoFar = [...dict.values()].filter((e) => e.declaration).length;
+                const placement = placementOf(native, model, configNatives.length + declaredSoFar);
+                if (placement.in === 'config')
+                    configNatives.push(placement.as);
+                else if (placement.in === 'dict')
+                    dict.set(listedTool.name, { tool: listedTool, native });
+                continue;
+            }
+            const writer = instructionToolOf(listedTool);
+            if (writer) {
+                instructionTexts.push(() => writer.instruction(toolContext));
+                continue;
+            }
+            const own = toolOf(listedTool);
+            const declaration = contractToolDeclaration(own ?? listedTool);
+            if (declaration) {
+                const key = typeof listedTool.name === 'string' ? listedTool.name : declaration.name;
+                dict.set(key, { tool: own ?? listedTool, declaration });
+            }
+            if (own?.instruction) {
+                const write = own.instruction.bind(own);
+                instructionTexts.push(() => write(toolContext));
+            }
+            if (own?.contents) {
+                const add = own.contents.bind(own);
+                contentWriters.push(() => add(contents, toolContext));
+            }
+        }
+    }
+    // ADK runs each tool's processLlmRequest in turn; its instruction lands in that order.
+    for (const text of instructionTexts) {
+        const written = await text();
+        if (written)
+            system = appendInstructions(system, [written]);
+    }
+    // ...and what it adds to the history (load_skill_resource's binary file, ADR 0083), after the history.
+    for (const write of contentWriters)
+        await write();
+    // 5. Everything the config says, read as the shim's mapping reads it.
+    const { toolChoice, strict } = toolChoiceOf(cfg);
+    const tools = [];
+    const declared = new Map();
+    const nativeTools = new Set();
+    for (const [name, entry] of dict) {
+        if (entry.native)
+            nativeTools.add(entry.native);
+        if (entry.declaration) {
+            tools.push(strict ? { ...entry.declaration, strict } : entry.declaration);
+            declared.set(name, entry.tool);
+        }
+    }
+    for (const native of configNatives)
+        nativeTools.add(native);
+    const schema = cfg.responseJsonSchema ?? cfg.responseSchema;
+    const jsonMode = !isObject(schema) && cfg.responseMimeType === 'application/json';
+    const reasoning = reasoningOf(cfg);
+    const sampling = samplingOf(cfg);
+    const systemPrompt = systemText(system);
+    const messages = contentsToMessages(contents).messages;
+    const request = {
+        model,
+        ...(systemPrompt !== undefined ? { system: systemPrompt } : {}),
+        messages,
+        ...(tools.length > 0 ? { tools } : {}),
+        ...(nativeTools.size > 0 ? { nativeTools: [...nativeTools] } : {}),
+        ...(toolChoice !== undefined ? { toolChoice } : {}),
+        ...(isObject(schema) ? { outputSchema: toContractJsonSchema(schema) } : {}),
+        ...(jsonMode ? { outputFormat: 'json' } : {}),
+        ...(reasoning !== undefined ? { reasoning } : {}),
+        ...(sampling ? { sampling } : {}),
+        stream: ctx.stream ?? false,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+    };
+    return { request, tools: declared };
+}