melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/compileNative.d.ts

@@ -0,0 +1,111 @@
+/**
+ * lib/compileNative.ts — an AgentSpec as the native runtime runs it: the
+ * NativeAgent the agent loop takes (ADR 0045, ADR 0073).
+ *
+ * WHY this file exists:
+ *   lib/compile.ts turns a YAML agent into a runtime-neutral AgentSpec, and
+ *   lib/compileAdk.ts builds ADK's LlmAgent from it. This file builds the
+ *   native loop's agent from the same spec (lib/runtime/native/request.ts,
+ *   NativeAgent), so both runtimes run the agent the YAML describes, with
+ *   the same tools, instruction and config. tests/compile.test.ts compiles
+ *   one spec both ways and requires the same first request.
+ *
+ * TOOLS: each resolved tool is handed to the loop as the own Tool or
+ * InstructionTool behind it (lib/tools/tool.ts), else as itself: an MCP
+ * tool, the skills toolset, a gated registry FunctionTool, which the loop
+ * runs by shape during the dual period (ADR 0071). A delegated subagent
+ * becomes a subagentTool holding its own NativeAgent, which the loop runs as
+ * a child loop (lib/runtime/native/delegate.ts, ADR 0074), a nested
+ * syndicate as its orchestrator's agent, a nested workflow syndicate as a
+ * workflowSubagentTool whose call walks the whole graph (ADR 0098); a remote A2A subagent is the own
+ * Tool the ADK runtime's FunctionTool wraps (lib/a2a/remoteAgent.ts).
+ *
+ * EVERY AGENT KEY COMPILES for the native loop: `context:` is handed to
+ * the loop, which compacts as ADK does (lib/runtime/native/compaction.ts,
+ * WS2-9); `mode: task` and `code_execution: gemini` pass through, the
+ * request declaring finish_task (lib/runtime/native/taskMode.ts) and asking
+ * Gemini for its code-execution tool (lib/runtime/native/request.ts). What
+ * native does not run yet (workflows, resuming an approval or a
+ * question, a caller's agent transform) is refused by the turn runner
+ * (lib/runtime/nativeTurn.ts), which owns those choices.
+ *
+ * THE MODEL: the loop calls a model through its contract adapter. A
+ * resolver may return an id, a contract adapter, an ADK shim (which carries
+ * one) or ADK's Gemini (TracedGemini), whose key reaches the registry's
+ * Gemini adapter. Any other ADK model class has no adapter behind it, so
+ * compileNative and nativeAdapterFor refuse it with UnsupportedOnRuntimeError
+ * before any model call, naming adkShim as the way to run it on native,
+ * rather than run the registry's model for that id in its place (ADR 0088).
+ * ADK classes are told apart by ADK's own Symbol.for marks, so this file
+ * imports nothing from ADK.
+ */
+import type { AgentSpec, CompileOptions, WorkflowSpec } from './compile.ts';
+import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+import type { ModelAdapter } from './models/contract.ts';
+import type { WorkflowSubagent } from './runtime/native/delegate.ts';
+import type { NativeAgent } from './runtime/native/request.ts';
+export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.ts';
+import type { WorkflowGraph } from './workflow/graph.ts';
+/**
+ * The class name of an ADK model the native runtime cannot run, else
+ * undefined: an ADK BaseLlm that is neither ADK's Gemini (TracedGemini
+ * included) nor a shim carrying a contract adapter (lib/models/adkShim.ts).
+ */
+export declare function unrunnableModelClass(resolved: unknown): string | undefined;
+/**
+ * The NativeAgent for `spec`. Throws when no model id is known, and
+ * UnsupportedOnRuntimeError when the resolver returned an ADK model class
+ * the loop cannot call (see the header).
+ */
+export declare function compileNative(spec: AgentSpec): NativeAgent;
+/**
+ * The model id a request is sent under, as ADK's LlmAgent sends it: the id
+ * of the model object the resolver returned (an ADK model or a contract
+ * adapter carries its own), else the id the resolver returned, else the
+ * spec's. A resolver may answer a YAML id with a model under another id (a
+ * gateway stand-in, a caller's alias); the adapter, the span and the
+ * circuit breaker then see that id on both runtimes.
+ */
+export declare function wireModelOf(spec: Pick<AgentSpec, 'modelId' | 'resolvedModel'>): string | undefined;
+/** A syndicate's orchestrator for the native loop: compileSpec, then compileNative. */
+export declare function compileNativeGraph(config: SyndicateYamlConfig, opts?: CompileOptions): Promise<NativeAgent>;
+/** A workflow syndicate for the native walk (lib/workflow/turn.ts): its graph, every agent by YAML name, and the tool nodes' lookup. */
+export interface NativeWorkflow {
+    name: string;
+    description: string;
+    graph: WorkflowGraph;
+    agents: Map<string, NativeAgent>;
+    resolveTool: (name: string) => unknown;
+}
+/**
+ * A workflow spec for the native walk: the graph, every agent compiled for
+ * native from the same specs ADK's assembleWorkflow builds its agents from,
+ * and the registry's lookup for tool nodes. A tool node ADK's compile
+ * refuses (an unregistered or long-running tool) is refused here, before
+ * any model call, with ADK's message.
+ */
+export declare function compileNativeWorkflow(spec: WorkflowSpec): NativeWorkflow;
+/**
+ * A nested workflow as the delegated subagent the native loop calls (ADR
+ * 0098): one call walks the whole graph with runNativeWorkflow on the child
+ * session lib/runtime/native/delegate.ts opened, as ADK's AgentTool runs a
+ * Workflow on its own Runner.
+ */
+export declare function workflowSubagentOf(workflow: NativeWorkflow): WorkflowSubagent;
+/** One subagent entry (a dispatch route) for the native loop: compileSubagentSpec, then compileNative. */
+export declare function compileNativeSubagent(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<NativeAgent>;
+/** What nativeAdapterFor reads from a spec: its model resolution, the other ids it calls, and its delegated subagents. */
+type NativeModelSpec = Pick<AgentSpec, 'modelId' | 'resolvedModel'> & Partial<Pick<AgentSpec, 'name' | 'fallbackModel' | 'context' | 'tools'>>;
+/**
+ * The loop's `adapterFor` under the same model resolution the ADK runtime
+ * uses: the leaf adapter behind what CompileOptions.resolveModel returns
+ * (an ADK shim carries its contract adapter, so a caller's BYOK key on a
+ * shimmed provider reaches the call), else resolveAdapter for the id
+ * (lib/models/registry.ts). The spec's own resolution, and each delegated
+ * subagent's, is reused for the id its agent runs under (wireModelOf).
+ * Each agent's `fallback_model:` and compaction `summary_model` are
+ * resolved here, as compileAdk resolves them at compile time, so a model
+ * class native cannot run is refused before any model call; any other id
+ * is resolved when first asked for. Each is kept.
+ */
+export declare function nativeAdapterFor(opts?: CompileOptions, spec?: NativeModelSpec | readonly NativeModelSpec[]): (model: string) => ModelAdapter;

package/dist/lib/compileNative.js

@@ -0,0 +1,278 @@
+/**
+ * lib/compileNative.ts — an AgentSpec as the native runtime runs it: the
+ * NativeAgent the agent loop takes (ADR 0045, ADR 0073).
+ *
+ * WHY this file exists:
+ *   lib/compile.ts turns a YAML agent into a runtime-neutral AgentSpec, and
+ *   lib/compileAdk.ts builds ADK's LlmAgent from it. This file builds the
+ *   native loop's agent from the same spec (lib/runtime/native/request.ts,
+ *   NativeAgent), so both runtimes run the agent the YAML describes, with
+ *   the same tools, instruction and config. tests/compile.test.ts compiles
+ *   one spec both ways and requires the same first request.
+ *
+ * TOOLS: each resolved tool is handed to the loop as the own Tool or
+ * InstructionTool behind it (lib/tools/tool.ts), else as itself: an MCP
+ * tool, the skills toolset, a gated registry FunctionTool, which the loop
+ * runs by shape during the dual period (ADR 0071). A delegated subagent
+ * becomes a subagentTool holding its own NativeAgent, which the loop runs as
+ * a child loop (lib/runtime/native/delegate.ts, ADR 0074), a nested
+ * syndicate as its orchestrator's agent, a nested workflow syndicate as a
+ * workflowSubagentTool whose call walks the whole graph (ADR 0098); a remote A2A subagent is the own
+ * Tool the ADK runtime's FunctionTool wraps (lib/a2a/remoteAgent.ts).
+ *
+ * EVERY AGENT KEY COMPILES for the native loop: `context:` is handed to
+ * the loop, which compacts as ADK does (lib/runtime/native/compaction.ts,
+ * WS2-9); `mode: task` and `code_execution: gemini` pass through, the
+ * request declaring finish_task (lib/runtime/native/taskMode.ts) and asking
+ * Gemini for its code-execution tool (lib/runtime/native/request.ts). What
+ * native does not run yet (workflows, resuming an approval or a
+ * question, a caller's agent transform) is refused by the turn runner
+ * (lib/runtime/nativeTurn.ts), which owns those choices.
+ *
+ * THE MODEL: the loop calls a model through its contract adapter. A
+ * resolver may return an id, a contract adapter, an ADK shim (which carries
+ * one) or ADK's Gemini (TracedGemini), whose key reaches the registry's
+ * Gemini adapter. Any other ADK model class has no adapter behind it, so
+ * compileNative and nativeAdapterFor refuse it with UnsupportedOnRuntimeError
+ * before any model call, naming adkShim as the way to run it on native,
+ * rather than run the registry's model for that id in its place (ADR 0088).
+ * ADK classes are told apart by ADK's own Symbol.for marks, so this file
+ * imports nothing from ADK.
+ */
+import { remoteAgentOwnTool } from './a2a/remoteAgent.js';
+import { compileSpec, compileSubagentSpec } from './compile.js';
+import { providerForModel, resolveAdapter } from './models/registry.js';
+import { subagentTool, workflowSubagentTool } from './runtime/native/delegate.js';
+import { servedThroughShim } from './runtime/native/selfCorrection.js';
+import { unsupportedOnNative } from './runtime/runtimeFlag.js';
+export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.js';
+import { instructionToolOf, toolOf, toolsetOf } from './tools/tool.js';
+import { buildWorkflowGraph } from './workflow/graph.js';
+import { refuseUnrunnableNodes, runNativeWorkflow } from './workflow/turn.js';
+/** A resolved tool as the loop holds it: the own Tool, InstructionTool or Toolset behind it, else the object itself. */
+function nativeTool(tool) {
+    return toolOf(tool) ?? instructionToolOf(tool) ?? toolsetOf(tool) ?? tool;
+}
+/** ADK's own marks on its model classes (BaseLlm, Gemini), registered with Symbol.for so they hold across copies of ADK. */
+const ADK_BASE_MODEL = Symbol.for('google.adk.baseModel');
+const ADK_GEMINI_MODEL = Symbol.for('google.adk.geminiModel');
+const marked = (value, mark) => !!value && typeof value === 'object' && value[mark] === true;
+/**
+ * The class name of an ADK model the native runtime cannot run, else
+ * undefined: an ADK BaseLlm that is neither ADK's Gemini (TracedGemini
+ * included) nor a shim carrying a contract adapter (lib/models/adkShim.ts).
+ */
+export function unrunnableModelClass(resolved) {
+    if (!marked(resolved, ADK_BASE_MODEL) || marked(resolved, ADK_GEMINI_MODEL))
+        return undefined;
+    if (isModelAdapter(resolved.adapter))
+        return undefined;
+    const name = resolved.constructor?.name;
+    return typeof name === 'string' && name ? name : 'BaseLlm';
+}
+/** Throws UnsupportedOnRuntimeError when `resolved` is an ADK model class native cannot run (see the header). */
+function refuseModelClass(resolved, modelId, where) {
+    const name = unrunnableModelClass(resolved);
+    if (!name)
+        return;
+    throw unsupportedOnNative(`the ADK model class ${name} that resolveModel returned${modelId ? ` for '${modelId}'` : ''}, which has no contract adapter behind it ` +
+        `(return the ModelAdapter itself, or adkShim(adapter) from melchizedek-agents/models/adkShim, to run it on native)`, where);
+}
+/**
+ * The NativeAgent for `spec`. Throws when no model id is known, and
+ * UnsupportedOnRuntimeError when the resolver returned an ADK model class
+ * the loop cannot call (see the header).
+ */
+export function compileNative(spec) {
+    refuseModelClass(spec.resolvedModel, spec.model ?? spec.modelId, spec.name);
+    const tools = [];
+    for (const entry of spec.tools) {
+        if (entry.kind === 'agent')
+            tools.push(subagentTool(compileNative(entry.agent)));
+        else if (entry.kind === 'workflow')
+            tools.push(workflowSubagentTool(workflowSubagentOf(compileNativeWorkflow(entry.workflow))));
+        else if (entry.kind === 'remote')
+            tools.push(remoteAgentOwnTool({ name: entry.name, description: entry.description, url: entry.url }));
+        else
+            tools.push(nativeTool(entry.tool));
+    }
+    const model = wireModelOf(spec);
+    if (!model)
+        throw new Error(`${spec.name}: no model id to run on (the YAML names none and the resolver returned none).`);
+    const agent = {
+        name: spec.name,
+        model,
+        instruction: spec.instruction,
+        tools,
+        generateContentConfig: spec.generateContentConfig,
+    };
+    if (spec.description)
+        agent.description = spec.description;
+    if (spec.globalInstruction !== undefined)
+        agent.globalInstruction = spec.globalInstruction;
+    if (spec.outputSchema)
+        agent.outputSchema = spec.outputSchema;
+    if (spec.includeContents !== undefined)
+        agent.includeContents = spec.includeContents;
+    if (spec.disallowTransferToParent !== undefined)
+        agent.disallowTransferToParent = spec.disallowTransferToParent;
+    if (spec.disallowTransferToPeers !== undefined)
+        agent.disallowTransferToPeers = spec.disallowTransferToPeers;
+    if (spec.codeExecution)
+        agent.codeExecution = spec.codeExecution;
+    if (spec.mode)
+        agent.mode = spec.mode;
+    if (spec.outputKey !== undefined)
+        agent.outputKey = spec.outputKey;
+    if (spec.fallbackModel)
+        agent.fallbackModel = spec.fallbackModel;
+    if (spec.context)
+        agent.context = spec.context;
+    return agent;
+}
+/**
+ * The model id a request is sent under, as ADK's LlmAgent sends it: the id
+ * of the model object the resolver returned (an ADK model or a contract
+ * adapter carries its own), else the id the resolver returned, else the
+ * spec's. A resolver may answer a YAML id with a model under another id (a
+ * gateway stand-in, a caller's alias); the adapter, the span and the
+ * circuit breaker then see that id on both runtimes.
+ */
+export function wireModelOf(spec) {
+    const resolved = spec.resolvedModel;
+    if (typeof resolved === 'string' && resolved)
+        return resolved;
+    const own = resolved && typeof resolved === 'object' ? resolved.model : undefined;
+    if (typeof own === 'string' && own)
+        return own;
+    return spec.modelId;
+}
+/** A syndicate's orchestrator for the native loop: compileSpec, then compileNative. */
+export async function compileNativeGraph(config, opts = {}) {
+    return compileNative(await compileSpec(config, opts));
+}
+/**
+ * A workflow spec for the native walk: the graph, every agent compiled for
+ * native from the same specs ADK's assembleWorkflow builds its agents from,
+ * and the registry's lookup for tool nodes. A tool node ADK's compile
+ * refuses (an unregistered or long-running tool) is refused here, before
+ * any model call, with ADK's message.
+ */
+export function compileNativeWorkflow(spec) {
+    const graph = buildWorkflowGraph(spec.config);
+    const agents = new Map();
+    for (const { yaml, spec: agentSpec } of spec.agents)
+        agents.set(yaml.name, compileNative(agentSpec));
+    refuseUnrunnableNodes(graph, spec.resolveTool);
+    return { name: spec.name, description: spec.description, graph, agents, resolveTool: spec.resolveTool };
+}
+/**
+ * A nested workflow as the delegated subagent the native loop calls (ADR
+ * 0098): one call walks the whole graph with runNativeWorkflow on the child
+ * session lib/runtime/native/delegate.ts opened, as ADK's AgentTool runs a
+ * Workflow on its own Runner.
+ */
+export function workflowSubagentOf(workflow) {
+    return {
+        name: workflow.name,
+        ...(workflow.description ? { description: workflow.description } : {}),
+        walk: (run) => runNativeWorkflow({
+            graph: workflow.graph,
+            agents: workflow.agents,
+            resolveTool: workflow.resolveTool,
+            sessions: run.sessions,
+            appName: run.appName,
+            userId: run.userId,
+            sessionId: run.sessionId,
+            userParts: run.userParts,
+            adapterFor: run.adapterFor,
+            selfCorrection: run.selfCorrection,
+            stream: false,
+            ...(run.signal ? { signal: run.signal } : {}),
+            ...(run.memory ? { memory: run.memory } : {}),
+            ...(run.log ? { log: run.log } : {}),
+            ...(run.credentials ? { credentials: run.credentials } : {}),
+        }),
+    };
+}
+/** One subagent entry (a dispatch route) for the native loop: compileSubagentSpec, then compileNative. */
+export async function compileNativeSubagent(subCfg, opts = {}) {
+    return compileNative(await compileSubagentSpec(subCfg, opts));
+}
+function isModelAdapter(value) {
+    return !!value && typeof value === 'object' && typeof value.generate === 'function' && typeof value.model === 'string';
+}
+/**
+ * The contract adapter behind what a resolver returned: an ADK shim's own
+ * adapter; for an ADK class that is not a shim (TracedGemini, ADK's Gemini)
+ * the registry's adapter under the key the instance carries, so a caller's
+ * BYOK key still pays for the call; else the registry's for the id.
+ */
+function adapterOf(resolved, model) {
+    if (isModelAdapter(resolved))
+        return resolved;
+    refuseModelClass(resolved, model, 'the native runtime');
+    if (typeof resolved === 'string')
+        return resolveAdapter(resolved || model);
+    if (!resolved || typeof resolved !== 'object')
+        return resolveAdapter(model);
+    const held = resolved;
+    // On ADK a shim declares the toolsDict, the reflection tool included, whatever its adapter (ADR 0097).
+    if (isModelAdapter(held.adapter))
+        return servedThroughShim(held.adapter);
+    // On Vertex AI the client authenticates with the platform's credentials, never a key (ADR 0023).
+    if (typeof held.apiKey === 'string' && held.apiKey && held.vertexai !== true) {
+        return resolveAdapter(model, { apiKey: held.apiKey, keyProvider: providerForModel(model) });
+    }
+    return resolveAdapter(model);
+}
+/**
+ * The loop's `adapterFor` under the same model resolution the ADK runtime
+ * uses: the leaf adapter behind what CompileOptions.resolveModel returns
+ * (an ADK shim carries its contract adapter, so a caller's BYOK key on a
+ * shimmed provider reaches the call), else resolveAdapter for the id
+ * (lib/models/registry.ts). The spec's own resolution, and each delegated
+ * subagent's, is reused for the id its agent runs under (wireModelOf).
+ * Each agent's `fallback_model:` and compaction `summary_model` are
+ * resolved here, as compileAdk resolves them at compile time, so a model
+ * class native cannot run is refused before any model call; any other id
+ * is resolved when first asked for. Each is kept.
+ */
+export function nativeAdapterFor(opts = {}, spec) {
+    const cache = new Map();
+    const known = new Map();
+    const learn = (s) => {
+        if (s.resolvedModel !== undefined) {
+            for (const id of [wireModelOf(s), s.modelId])
+                if (id && !known.has(id))
+                    known.set(id, s.resolvedModel);
+        }
+        for (const id of [s.fallbackModel, s.context?.summary_model]) {
+            if (!id || known.has(id) || !opts.resolveModel)
+                continue;
+            const resolved = opts.resolveModel(id);
+            refuseModelClass(resolved, id, s.name ?? 'the native runtime');
+            known.set(id, resolved);
+        }
+        for (const entry of s.tools ?? []) {
+            if (entry.kind === 'agent')
+                learn(entry.agent);
+            // A nested workflow's agents run under the caller's lookup (ADR 0098).
+            else if (entry.kind === 'workflow')
+                for (const node of entry.workflow.agents)
+                    learn(node.spec);
+        }
+    };
+    // A workflow's agents share one lookup: every node's spec is learned.
+    for (const s of spec === undefined ? [] : Array.isArray(spec) ? spec : [spec])
+        learn(s);
+    return (model) => {
+        const held = cache.get(model);
+        if (held)
+            return held;
+        const resolved = known.has(model) ? known.get(model) : opts.resolveModel ? opts.resolveModel(model) : model;
+        const adapter = adapterOf(resolved, model);
+        cache.set(model, adapter);
+        return adapter;
+    };
+}

package/dist/lib/config.d.ts

@@ -52,11 +52,12 @@ export declare const DEFAULT_GPT_MODEL = "gpt-5-mini";
  */
 export declare const DEFAULT_GROK_MODEL = "grok-4.7";
 /**
- * Reasoning effort sent with grok-4.5/4.7 requests: 'low' | 'medium' | 'high'
- * (xAI's own default is 'high'; 4.7 adds 'xhigh'). Pinned to MEDIUM — deeper
- * than low without high's latency and token cost. Source: docs.x.ai › Model
- * capabilities › Text › Reasoning › Effort levels. Older grok ids don't
- * accept the param and never receive it (lib/models/grokLlm.ts).
+ * Reasoning effort sent with grok-4.5, 4.6 and 4.7 requests that set no
+ * `reasoning:`: 'low' | 'medium' | 'high' (xAI's own default is 'high'; 4.7
+ * adds 'xhigh'). Pinned to MEDIUM — deeper than low without high's latency
+ * and token cost. Source: docs.x.ai › Model capabilities › Text › Reasoning ›
+ * Effort levels. Older grok ids don't accept the param and never receive it
+ * (lib/models/grokAdapter.ts).
  */
 export declare const DEFAULT_GROK_REASONING_EFFORT = "medium";
 /**

package/dist/lib/config.js

@@ -53,11 +53,12 @@ export const DEFAULT_GPT_MODEL = 'gpt-5-mini';
  */
 export const DEFAULT_GROK_MODEL = 'grok-4.7';
 /**
- * Reasoning effort sent with grok-4.5/4.7 requests: 'low' | 'medium' | 'high'
- * (xAI's own default is 'high'; 4.7 adds 'xhigh'). Pinned to MEDIUM — deeper
- * than low without high's latency and token cost. Source: docs.x.ai › Model
- * capabilities › Text › Reasoning › Effort levels. Older grok ids don't
- * accept the param and never receive it (lib/models/grokLlm.ts).
+ * Reasoning effort sent with grok-4.5, 4.6 and 4.7 requests that set no
+ * `reasoning:`: 'low' | 'medium' | 'high' (xAI's own default is 'high'; 4.7
+ * adds 'xhigh'). Pinned to MEDIUM — deeper than low without high's latency
+ * and token cost. Source: docs.x.ai › Model capabilities › Text › Reasoning ›
+ * Effort levels. Older grok ids don't accept the param and never receive it
+ * (lib/models/grokAdapter.ts).
  */
 export const DEFAULT_GROK_REASONING_EFFORT = 'medium';
 /**

package/dist/lib/doctor.d.ts

@@ -18,11 +18,15 @@
  * The routing and capability judgments are not re-implemented here: they
  * come from lib/models/gateway.ts and lib/models/capabilities.ts, the same
  * modules the registry and the A2A server use, so the report cannot
- * disagree with what a run would do.
+ * disagree with what a run would do. The runtime line comes from
+ * lib/runtime/runtimeFlag.ts, which a turn reads (ADR 0102); whether
+ * @google/adk is installed is a module resolution, so the doctor never
+ * loads ADK to answer it.
  */
 import type { Platform } from './models/endpoints.ts';
 import type { CapabilityGap, CapabilityReport } from './models/capabilities.ts';
 import type { ProviderId } from './models/providerMap.ts';
+import type { RuntimeName, RuntimeSource } from './runtime/runtimeFlag.ts';
 /**
  * What a file costs to run: `keyless` (all Ollama), a single provider's id
  * when every agent shares one (`gemini`, `anthropic`, `openai`, `xai` — one
@@ -81,8 +85,25 @@ export interface Unlock {
     /** Syndicates this one variable would move from blocked to ready. */
     syndicates: string[];
 }
+/** The runtime a turn would run on here, where that came from, and the optional ADK peer (ADR 0102). */
+export interface DoctorRuntime {
+    /** The runtime in use; undefined when MELCHIZEDEK_RUNTIME holds a value no turn accepts (`problem` says so). */
+    runtime?: RuntimeName;
+    /** Where it came from: MELCHIZEDEK_RUNTIME, or the default (a turn's own option is the caller's, not the environment's). */
+    source?: RuntimeSource;
+    /** @google/adk: whether it resolves from here, its version, and whether the runtime in use needs it. */
+    adk: {
+        installed: boolean;
+        version?: string;
+        needed: boolean;
+    };
+    /** Why no turn would run as configured, if none would. */
+    problem?: string;
+}
 export interface DoctorResult {
     agentsDir: string;
+    /** The runtime in use and whether @google/adk is installed. */
+    runtime: DoctorRuntime;
     syndicates: DoctorSyndicate[];
     unlocks: Unlock[];
     gateway: {
@@ -110,6 +131,12 @@ export interface DoctorEndpoint {
     /** Cloud platforms are tested against mocks only (ADR 0023). */
     liveVerified: boolean;
 }
+/**
+ * The runtime a turn would run on under this environment (lib/runtime/
+ * runtimeFlag.ts), where that came from, and whether @google/adk resolves.
+ * `adk` without the package is a problem: every turn would fail.
+ */
+export declare function runtimeReport(env?: NodeJS.ProcessEnv, adkResolvable?: (module: string) => boolean): DoctorRuntime;
 /** One row per provider that is not on its vendor's public API with an env key. */
 export declare function endpointRows(): DoctorEndpoint[];
 export declare const CONSOLE_URLS: Record<ProviderId, string>;

package/dist/lib/doctor.js

@@ -18,7 +18,10 @@
  * The routing and capability judgments are not re-implemented here: they
  * come from lib/models/gateway.ts and lib/models/capabilities.ts, the same
  * modules the registry and the A2A server use, so the report cannot
- * disagree with what a run would do.
+ * disagree with what a run would do. The runtime line comes from
+ * lib/runtime/runtimeFlag.ts, which a turn reads (ADR 0102); whether
+ * @google/adk is installed is a module resolution, so the doctor never
+ * loads ADK to answer it.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -30,6 +33,7 @@ import { CAPABILITY_LABELS, capabilityGaps, describeCapabilities } from './model
 import { credentialSource, endpointFromEnv, endpointLabel, endpointProblems, PLATFORM_SDK, PLATFORMS_FOR } from './models/endpoints.js';
 import { GATEWAY_ENV, GATEWAY_KEY_ENV, GATEWAYS, gatewayConfig, gatewayProblem, gatewayUsable, } from './models/gateway.js';
 import { PROVIDERS } from './models/providerMap.js';
+import { describeRuntime } from './runtime/runtimeFlag.js';
 function resolvable(module) {
     try {
         createRequire(import.meta.url).resolve(module);
@@ -39,6 +43,52 @@ function resolvable(module) {
         return false;
     }
 }
+/** The installed version of a package that resolves from here, read from its package.json (its exports map may hide it). */
+function installedVersion(module) {
+    try {
+        let dir = path.dirname(createRequire(import.meta.url).resolve(module));
+        for (let i = 0; i < 8; i++) {
+            const file = path.join(dir, 'package.json');
+            if (fs.existsSync(file)) {
+                const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (pkg.name === module)
+                    return pkg.version;
+            }
+            const up = path.dirname(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    catch {
+        // Not resolvable, or unreadable: no version to report.
+    }
+    return undefined;
+}
+/** The ADK peer, as an install command names it. */
+const ADK_PEER = '@google/adk';
+/**
+ * The runtime a turn would run on under this environment (lib/runtime/
+ * runtimeFlag.ts), where that came from, and whether @google/adk resolves.
+ * `adk` without the package is a problem: every turn would fail.
+ */
+export function runtimeReport(env = process.env, adkResolvable = resolvable) {
+    const installed = adkResolvable(ADK_PEER);
+    const adk = { installed, ...(installed && installedVersion(ADK_PEER) ? { version: installedVersion(ADK_PEER) } : {}) };
+    let chosen;
+    try {
+        chosen = describeRuntime(undefined, env);
+    }
+    catch (err) {
+        return { adk: { ...adk, needed: false }, problem: err instanceof Error ? err.message : String(err) };
+    }
+    const needed = chosen.runtime === 'adk';
+    return {
+        ...chosen,
+        adk: { ...adk, needed },
+        ...(needed && !installed ? { problem: `MELCHIZEDEK_RUNTIME=adk needs ${ADK_PEER}, which is not installed: npm install ${ADK_PEER}@~2.2.0, or unset MELCHIZEDEK_RUNTIME to run on native` } : {}),
+    };
+}
 /** One row per provider that is not on its vendor's public API with an env key. */
 export function endpointRows() {
     const rows = [];
@@ -155,6 +205,7 @@ function needsOf(agent, delegates = false) {
         tools: agent.tools ?? [],
         outputSchema: agent.outputSchema,
         generateContentConfig: agent.generateContentConfig,
+        reasoning: agent.reasoning,
         delegates,
     };
 }
@@ -380,7 +431,7 @@ export function runDoctor(options = {}) {
     for (const s of syndicates)
         counts[s.verdict.state]++;
     flagMemoryNamespaces(syndicates);
-    return { agentsDir, syndicates, unlocks, gateway, endpoints: endpointRows(), counts };
+    return { agentsDir, runtime: runtimeReport(), syndicates, unlocks, gateway, endpoints: endpointRows(), counts };
 }
 // ── Rendering ────────────────────────────────────────────────────────────────
 const ANSI = {
@@ -416,6 +467,17 @@ export function renderDoctor(result, opts = {}) {
             : `${c.green}${text}${c.reset}`;
     lines.push(`${c.bold}melchizedek doctor${c.reset} ${c.dim}· ${result.agentsDir}${c.reset}`);
     lines.push('');
+    // The runtime a turn would run on, where that came from, and the ADK peer (ADR 0102).
+    if (result.runtime) {
+        const rt = result.runtime;
+        const adk = rt.adk.installed
+            ? `${ADK_PEER} ${rt.adk.version ?? ''}`.trimEnd() + ' installed'
+            : `${ADK_PEER} not installed${rt.adk.needed ? '' : ' (needed only for MELCHIZEDEK_RUNTIME=adk)'}`;
+        const source = rt.source === 'default' ? 'the default' : rt.source;
+        lines.push(rt.problem
+            ? `runtime     ${c.red}✗${c.reset} ${rt.runtime ? `${rt.runtime} ${c.dim}(${source})${c.reset} · ` : ''}${c.red}${rt.problem}${c.reset}`
+            : `runtime     ${c.green}✓${c.reset} ${rt.runtime} ${c.dim}(${source})${c.reset} · ${c.dim}${adk}${c.reset}`);
+    }
     // Provider line: what is funded, and how. Each provider is probed with an
     // id of its own prefix, so the line names ITS key (a fallthrough once put
     // xAI's key beside Moonshot).

package/dist/lib/index.d.ts

@@ -14,6 +14,10 @@
 export { loadSyndicate, loadSyndicateFromRegistry, parseCliBindings, validateRegistryConfig, } from './loadSyndicate.ts';
 export type { AgentYamlConfig, LoadSyndicateOptions, SubagentYamlConfig, SyndicateYamlConfig, VariableMap, } from './loadSyndicate.ts';
 export { runSyndicateTurn, ingestTurnMemory } from './runtime/syndicateTurn.ts';
+export { DEFAULT_RUNTIME, describeRuntime, AdkNotInstalledError, adkInstalled } from './runtime/syndicateTurn.ts';
+export type { RuntimeName, RuntimeSource } from './runtime/syndicateTurn.ts';
+export { InProcessSessionService } from './runtime/sessions.ts';
+export { asAdkSessionService, asSessionService } from './runtime/adkSessionBridge.ts';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.ts';
 export type { PendingApproval } from './runtime/approvals.ts';
 export type { DrainedRun, MessagePart, TurnUsage, RouteDecision, SyndicateTurnOptions, SyndicateTurnResult, TraceOptions, TurnEvents, TurnStage, } from './runtime/syndicateTurn.ts';
@@ -37,7 +41,8 @@ export type { RemoteAnswer } from './a2a/remoteAgent.ts';
 export { resolveTools, registerTool, registeredToolNames } from './toolRegistry.ts';
 export { registerGuard, resolveGuards } from './guards/index.ts';
 export type { Guard, GuardResult } from './guards/index.ts';
-export { defineTool, toFunctionTool } from './tools/toolContract.ts';
+export { defineTool } from './tools/toolContract.ts';
+export { toFunctionTool } from './tools/adkTool.ts';
 export { modelExtractor, geminiEmbedder, openAiCompatibleEmbedder, memoryProvidersFromEnv, } from './memory/providers.ts';
 export type { Embedder, MemoryExtractor } from './memory/providers.ts';
 export { eraseScope } from './memory/erase.ts';

package/dist/lib/index.js

@@ -15,6 +15,11 @@
 export { loadSyndicate, loadSyndicateFromRegistry, parseCliBindings, validateRegistryConfig, } from './loadSyndicate.js';
 // ── Run it ──────────────────────────────────────────────────────────────────
 export { runSyndicateTurn, ingestTurnMemory } from './runtime/syndicateTurn.js';
+// The runtime in use (native by default since 0.20.0) and the optional ADK peer (ADR 0102).
+export { DEFAULT_RUNTIME, describeRuntime, AdkNotInstalledError, adkInstalled } from './runtime/syndicateTurn.js';
+// An in-process session store that needs no ADK; runSyndicateTurn takes it through asAdkSessionService.
+export { InProcessSessionService } from './runtime/sessions.js';
+export { asAdkSessionService, asSessionService } from './runtime/adkSessionBridge.js';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.js';
 export { compileGraph, compileSubagent } from './compile.js';
 export { compileWorkflow, isWorkflowSyndicate, describeInput } from './workflow.js';
@@ -28,7 +33,8 @@ export { RemoteA2AAgent, remoteAgentTool } from './a2a/remoteAgent.js';
 // ── Extend it ───────────────────────────────────────────────────────────────
 export { resolveTools, registerTool, registeredToolNames } from './toolRegistry.js';
 export { registerGuard, resolveGuards } from './guards/index.js';
-export { defineTool, toFunctionTool } from './tools/toolContract.js';
+export { defineTool } from './tools/toolContract.js';
+export { toFunctionTool } from './tools/adkTool.js';
 // ── Memory ──────────────────────────────────────────────────────────────────
 export { modelExtractor, geminiEmbedder, openAiCompatibleEmbedder, memoryProvidersFromEnv, } from './memory/providers.js';
 export { eraseScope } from './memory/erase.js';