melchizedek-agents 0.17.0 → 0.19.0

package/dist/lib/a2a/executor.js

@@ -8,6 +8,12 @@
  * cancellation, the per-server concurrency cap, and memory ingestion after
  * the reply. Every turn semantic — dispatch, delegation, relay fallback,
  * guards, the step cap — is the runtime's.
+ *
+ * Its stores are the engine's (ADR 0080): it takes a session store and a
+ * memory service with either face, the engine's or ADK's, reads a session
+ * through the engine's SessionService, and hands the turn runner the faces
+ * its fixed signature names through the bridges
+ * (lib/runtime/adkSessionBridge.ts, lib/runtime/adkMemoryBridge.ts).
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -17,9 +23,12 @@ import { nestedLoader } from '../loadSyndicate.js';
 import { configDigest } from '../observability/lineage.js';
 import { turnLockKey } from './turnLock.js';
 import { ingestTurnMemory, runSyndicateTurn } from '../runtime/syndicateTurn.js';
+import { asAdkSessionService, asSessionService } from '../runtime/adkSessionBridge.js';
+import { asAdkMemoryService } from '../runtime/adkMemoryBridge.js';
 import { approvalResponsePart, describeApproval, pendingApproval } from '../runtime/approvals.js';
 import { declaresApprovals } from '../compile.js';
 import { describeInput } from '../runtime/syndicateTurn.js';
+import { describeConsent } from '../runtime/credentials.js';
 export const requestContextStorage = new AsyncLocalStorage();
 /** The app name every A2A session and memory silo is stored under. */
 export const A2A_APP_NAME = 'melchizedek-a2a';
@@ -122,28 +131,64 @@ export function a2aPartsToMessage(rawParts) {
     return { parts };
 }
 const NO_USAGE = { llmCalls: 0, inputTokens: 0, outputTokens: 0, thinkingTokens: 0 };
-/** Concurrency cap and in-flight registry shared by all executors. */
+/** Concurrency caps and in-flight registry shared by all executors. */
 export class TaskLimiter {
     max;
+    perScope;
+    perCaller;
     running = new Map();
+    /** taskId → the keys it counts against, so release frees exactly those. */
+    keysOf = new Map();
+    counts = new Map();
     draining = false;
     idleWaiters = [];
-    constructor(max) {
+    constructor(max, limits = {}) {
         this.max = max > 0 ? max : Infinity;
+        this.perScope = limits.perScope && limits.perScope > 0 ? limits.perScope : Infinity;
+        this.perCaller = limits.perCaller && limits.perCaller > 0 ? limits.perCaller : Infinity;
+    }
+    /**
+     * Why a task for this scope and caller may not start now, or undefined.
+     * Checked before acquire() so the refusal can name the cap that was hit.
+     */
+    refusal(who = {}) {
+        if (this.draining)
+            return 'The server is shutting down; retry shortly.';
+        if (this.running.size >= this.max)
+            return `The server is at its limit of ${this.max} concurrent tasks; retry shortly.`;
+        if (who.scopeKey && (this.counts.get(`s:${who.scopeKey}`) ?? 0) >= this.perScope) {
+            return `This user already has ${this.perScope} tasks running, the most allowed at once; retry when one finishes.`;
+        }
+        if (who.caller && (this.counts.get(`c:${who.caller}`) ?? 0) >= this.perCaller) {
+            return `This caller already has ${this.perCaller} tasks running, the most allowed at once; retry when one finishes.`;
+        }
+        return undefined;
     }
     get inFlight() {
         return this.running.size;
     }
-    /** Reserve a slot. Returns undefined when saturated or shutting down. */
-    acquire(taskId) {
-        if (this.draining || this.running.size >= this.max)
+    /** Reserve a slot. Returns undefined when any cap is reached or the server is shutting down. */
+    acquire(taskId, who = {}) {
+        if (this.refusal(who))
             return undefined;
         const controller = new AbortController();
         this.running.set(taskId, controller);
+        const keys = [who.scopeKey && `s:${who.scopeKey}`, who.caller && `c:${who.caller}`].filter((k) => !!k);
+        for (const k of keys)
+            this.counts.set(k, (this.counts.get(k) ?? 0) + 1);
+        this.keysOf.set(taskId, keys);
         return controller;
     }
     release(taskId) {
         this.running.delete(taskId);
+        for (const k of this.keysOf.get(taskId) ?? []) {
+            const n = (this.counts.get(k) ?? 1) - 1;
+            if (n > 0)
+                this.counts.set(k, n);
+            else
+                this.counts.delete(k);
+        }
+        this.keysOf.delete(taskId);
         if (this.running.size === 0)
             for (const w of this.idleWaiters.splice(0))
                 w();
@@ -267,6 +312,39 @@ function publishApprovalRequest(eventBus, taskId, contextId, pending) {
         metadata: undefined,
     }));
 }
+/**
+ * A call waits for an OAuth grant (ADR 0085): the task ends input-required,
+ * naming the provider, with a data part carrying the authorization URL and
+ * its state nonce. The person opens the URL; the server's callback stores
+ * the grant; the next message on the conversation resumes the call. The
+ * part carries no token, code or verifier.
+ */
+function publishConsentRequest(eventBus, taskId, contextId, pending) {
+    const message = statusMessage(taskId, contextId, `Authorization needed: ${describeConsent(pending)}. Open ${pending.authUri} to authorize, then send any message on this conversation to continue.`);
+    message.parts.push({
+        content: {
+            $case: 'data',
+            value: {
+                type: 'consent_request',
+                consent_id: pending.id,
+                agent: pending.agent,
+                provider: pending.provider,
+                authorization_url: pending.authUri,
+                state: pending.state,
+                scopes: pending.scopes,
+            },
+        },
+        metadata: undefined,
+        filename: '',
+        mediaType: 'application/json',
+    });
+    eventBus.publish(AgentEvent.statusUpdate({
+        taskId,
+        contextId,
+        status: { state: TaskState.TASK_STATE_INPUT_REQUIRED, message, timestamp: new Date().toISOString() },
+        metadata: undefined,
+    }));
+}
 /**
  * The caller's answer to the open approval, from the raw A2A parts: a data
  * part `{ approval: { id, approved } }` naming that request, or the text
@@ -339,8 +417,16 @@ export function answerStream(eventBus, taskId, contextId) {
 export class SyndicateExecutor {
     opts;
     configHash;
+    /** The store as the engine reads it. */
+    sessions;
+    /** The faces the turn runner's fixed signature names (ADR 0045 item 4). */
+    turnSessions;
+    turnMemory;
     constructor(opts) {
         this.opts = opts;
+        this.sessions = asSessionService(opts.sessionService);
+        this.turnSessions = asAdkSessionService(opts.sessionService);
+        this.turnMemory = opts.memoryService ? asAdkMemoryService(opts.memoryService) : undefined;
     }
     /** Provenance stamp for every turn this executor serves (lineage.ts). */
     configHashFor() {
@@ -367,6 +453,8 @@ export class SyndicateExecutor {
         // Reports the task once: to the task log and metrics, and its spend to
         // the policy. Never throws into the task.
         let reported = false;
+        // The turn's trace (the last root span started: a dispatch turn's answer).
+        let traceId;
         const report = async (ctx, status, reason, usage = NO_USAGE) => {
             if (reported)
                 return;
@@ -382,6 +470,9 @@ export class SyndicateExecutor {
             }
             try {
                 this.opts.onTaskEnd?.({
+                    taskId,
+                    traceId,
+                    ...(ctx?.traceparent ? { callerTraceId: ctx.traceparent.split('-')[1] } : {}),
                     agentId,
                     syndicate: config.syndicate_name,
                     caller: ctx?.caller,
@@ -395,6 +486,21 @@ export class SyndicateExecutor {
             catch {
                 /* a broken log sink must not fail the task */
             }
+            try {
+                this.opts.onAudit?.({
+                    event: 'task.end',
+                    outcome: status,
+                    caller: ctx?.caller,
+                    scopeHash: scopeKey ? createHash('sha256').update(scopeKey).digest('hex').slice(0, 12) : undefined,
+                    sourceIp: ctx?.sourceIp,
+                    agentId,
+                    taskId,
+                    detail: { syndicate: config.syndicate_name, ...(reason ? { reason } : {}), ...(traceId ? { traceId } : {}), durationMs: Date.now() - started, llmCalls: usage.llmCalls },
+                });
+            }
+            catch {
+                /* nor a broken audit sink */
+            }
         };
         let ctxForReport;
         try {
@@ -443,11 +549,10 @@ export class SyndicateExecutor {
                     return;
                 }
             }
-            slot = this.opts.limiter.acquire(taskId);
+            const who = { scopeKey: ctx.scopeKey, caller: ctx.caller };
+            slot = this.opts.limiter.acquire(taskId, who);
             if (!slot) {
-                const why = this.opts.limiter.isDraining
-                    ? 'The server is shutting down; retry shortly.'
-                    : `The server is at its limit of ${this.opts.limiter.max} concurrent tasks; retry shortly.`;
+                const why = this.opts.limiter.refusal(who) ?? 'The server is at capacity; retry shortly.';
                 warn(`Task ${short} rejected — ${why}`);
                 publishFinal(eventBus, taskId, contextId, 'rejected', why);
                 await report(ctx, 'rejected', 'capacity');
@@ -476,8 +581,10 @@ export class SyndicateExecutor {
             // Approvals (ADR 0028): while a gated call waits, a message is its
             // answer, or the request is repeated without spending a model call.
             if (declaresApprovals(config)) {
-                const session = await this.opts.sessionService.getSession({ appName, userId, sessionId: contextId });
-                const pending = pendingApproval(session?.events ?? []);
+                const session = await this.sessions.get({ appName, userId, sessionId: contextId });
+                // The stored Event JSON either way (ADR 0052): pendingApproval still
+                // names ADK's Event, which a TurnEvent reaches only through a cast.
+                const pending = pendingApproval((session?.events ?? []));
                 if (pending) {
                     const answer = approvalAnswer(rawParts, pending);
                     if (!answer) {
@@ -496,16 +603,21 @@ export class SyndicateExecutor {
                 appName,
                 userId,
                 sessionId: contextId,
-                sessionService: this.opts.sessionService,
-                memoryService: this.opts.memoryService,
+                sessionService: this.turnSessions,
+                memoryService: this.turnMemory,
                 compile: this.opts.compileFor(ctx),
                 signal: slot.signal,
                 deadlineMs: this.opts.taskTimeoutMs,
+                ...(this.opts.toolCredentials ? { toolCredentials: this.opts.toolCredentials } : {}),
                 streaming: !!stream,
                 trace: {
                     taskId,
                     configHash: this.configHashFor(),
                     attributes: surfaceAttributes(ctx),
+                    traceparent: ctx.traceparent,
+                    onSpanStart: (ids) => {
+                        traceId = ids.traceId;
+                    },
                 },
                 events: {
                     onProgress: (text) => publishWorking(eventBus, taskId, contextId, text),
@@ -532,6 +644,12 @@ export class SyndicateExecutor {
                 await report(ctx, 'input-required', 'approval', u);
                 return;
             }
+            if (result.status === 'input-required' && result.consent) {
+                log(`⏸ Task ${short} waiting for ${result.consent.provider} authorization after ${spent}`);
+                publishConsentRequest(eventBus, taskId, contextId, result.consent);
+                await report(ctx, 'input-required', 'consent', u);
+                return;
+            }
             if (result.status === 'input-required' && result.input) {
                 log(`⏸ Task ${short} waiting for input from ${result.input.node} after ${spent}`);
                 publishInputRequest(eventBus, taskId, contextId, result.input);
@@ -550,11 +668,11 @@ export class SyndicateExecutor {
             // Long-term memory: there is no "session end" on a server, so ingest
             // after every completed task. Runs AFTER the final publish, so it never
             // delays the reply, and a failure here never fails the task.
-            if (this.opts.memoryService) {
+            if (this.turnMemory) {
                 try {
                     await ingestTurnMemory({
-                        memoryService: this.opts.memoryService,
-                        sessionService: this.opts.sessionService,
+                        memoryService: this.turnMemory,
+                        sessionService: this.turnSessions,
                         appName,
                         userId,
                         sessionId: contextId,

package/dist/lib/a2a/remoteAgent.d.ts

@@ -12,7 +12,9 @@
  *
  * Built on the official A2A SDK client with its v0.3 compatibility layer on,
  * so a remote agent may speak A2A 1.0 (e.g. Microsoft Foundry) or 0.3 (most
- * other platforms today); the card decides. It does not depend on ADK.
+ * other platforms today); the card decides. The client does not depend on
+ * ADK, and the tool is the engine's own (remoteAgentOwnTool); the ADK
+ * runtime receives it through toFunctionTool (remoteAgentTool).
  *
  * Security:
  *   - Every URL — the card and the endpoint the card names — passes the
@@ -27,7 +29,8 @@
  */
 import type { AgentCard, Message, Task } from '@a2a-js/sdk';
 import type { Client } from '@a2a-js/sdk/client';
-import { FunctionTool } from '@google/adk';
+import type { FunctionTool } from '@google/adk';
+import type { Tool } from '../tools/tool.ts';
 export interface RemoteAnswer {
     state: string;
     text: string;
@@ -79,13 +82,25 @@ export declare class RemoteA2AAgent {
 export declare function remoteContextId(localSessionId: string | undefined, subagentName: string): string | undefined;
 /** Render a remote result as the tool output the orchestrator reads. */
 export declare function remoteToolOutput(name: string, answer: RemoteAnswer): string;
-/**
- * The subagent as a tool with AgentTool's contract (one `request` string), so
- * an orchestrator delegates to it exactly as to a local subagent. Failures
- * come back as readable text, never as a throw into the runner.
- */
-export declare function remoteAgentTool(params: {
+/** What a remote agent tool is built from: the subagent's name and description, and where it is served. */
+export interface RemoteAgentToolParams {
     name: string;
     description: string;
     url: string;
-}): FunctionTool;
+}
+/**
+ * The subagent as an own Tool (lib/tools/tool.ts, ADR 0062) with AgentTool's
+ * contract (one `request` string), so an orchestrator delegates to it
+ * exactly as to a local subagent, on either runtime. The remote
+ * conversation is keyed by the local session (`ctx.sessionId`), and the call
+ * aborts with the turn (`ctx.signal`). Failures come back as readable text,
+ * never as a throw into the runner.
+ */
+export declare function remoteAgentOwnTool(params: RemoteAgentToolParams): Tool;
+/**
+ * The remote agent tool as the ADK runtime runs it: the FunctionTool
+ * toFunctionTool (lib/tools/adkTool.ts) makes of remoteAgentOwnTool, which
+ * declares the same parameters the hand-built FunctionTool declared and
+ * carries the own Tool for toolOf().
+ */
+export declare function remoteAgentTool(params: RemoteAgentToolParams): FunctionTool;

package/dist/lib/a2a/remoteAgent.js

@@ -12,7 +12,9 @@
  *
  * Built on the official A2A SDK client with its v0.3 compatibility layer on,
  * so a remote agent may speak A2A 1.0 (e.g. Microsoft Foundry) or 0.3 (most
- * other platforms today); the card decides. It does not depend on ADK.
+ * other platforms today); the card decides. The client does not depend on
+ * ADK, and the tool is the engine's own (remoteAgentOwnTool); the ADK
+ * runtime receives it through toFunctionTool (remoteAgentTool).
  *
  * Security:
  *   - Every URL — the card and the endpoint the card names — passes the
@@ -28,9 +30,9 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { Role, TaskState } from '@a2a-js/sdk';
 import { ClientFactory, DefaultAgentCardResolver, JsonRpcTransportFactory, RestTransportFactory } from '@a2a-js/sdk/client';
-import { FunctionTool } from '@google/adk';
 import { checkHost } from '../net/addressGuard.js';
 import { currentTurnSignal } from '../runtime/turnControl.js';
+import { toFunctionTool } from '../tools/adkTool.js';
 const FETCH_TIMEOUT_MS = 30_000;
 const POLL_INTERVAL_MS = 1_500;
 const DEFAULT_TASK_TIMEOUT_MS = 10 * 60 * 1000;
@@ -234,29 +236,35 @@ export function remoteToolOutput(name, answer) {
     return `Error: remote agent ${name} ended in state '${answer.state}'${answer.text ? ` — ${answer.text}` : ''}.`;
 }
 /**
- * The subagent as a tool with AgentTool's contract (one `request` string), so
- * an orchestrator delegates to it exactly as to a local subagent. Failures
- * come back as readable text, never as a throw into the runner.
+ * The subagent as an own Tool (lib/tools/tool.ts, ADR 0062) with AgentTool's
+ * contract (one `request` string), so an orchestrator delegates to it
+ * exactly as to a local subagent, on either runtime. The remote
+ * conversation is keyed by the local session (`ctx.sessionId`), and the call
+ * aborts with the turn (`ctx.signal`). Failures come back as readable text,
+ * never as a throw into the runner.
  */
-export function remoteAgentTool(params) {
+export function remoteAgentOwnTool(params) {
     const client = new RemoteA2AAgent(params.url);
-    return new FunctionTool({
+    const declaration = {
         name: params.name,
         description: params.description || `Remote agent ${params.name}`,
         parameters: {
-            type: 'OBJECT',
-            properties: { request: { type: 'STRING', description: `What to ask ${params.name}.` } },
+            type: 'object',
+            properties: { request: { type: 'string', description: `What to ask ${params.name}.` } },
             required: ['request'],
         },
-        execute: async (input, toolContext) => {
-            const args = (input ?? {});
+    };
+    return {
+        name: params.name,
+        declaration: () => declaration,
+        execute: async (args, ctx) => {
             const request = String(args?.request ?? '').trim();
             if (!request)
                 return `Error: ${params.name} needs a request.`;
             try {
                 const answer = await client.send(request, {
-                    contextId: remoteContextId(toolContext?.invocationContext?.session?.id, params.name),
-                    signal: currentTurnSignal(),
+                    contextId: remoteContextId(ctx?.sessionId, params.name),
+                    signal: ctx?.signal ?? currentTurnSignal(),
                 });
                 return remoteToolOutput(params.name, answer);
             }
@@ -264,5 +272,14 @@ export function remoteAgentTool(params) {
                 return `Error: remote agent ${params.name} could not be reached (${err instanceof Error ? err.message : String(err)}).`;
             }
         },
-    });
+    };
+}
+/**
+ * The remote agent tool as the ADK runtime runs it: the FunctionTool
+ * toFunctionTool (lib/tools/adkTool.ts) makes of remoteAgentOwnTool, which
+ * declares the same parameters the hand-built FunctionTool declared and
+ * carries the own Tool for toolOf().
+ */
+export function remoteAgentTool(params) {
+    return toFunctionTool(remoteAgentOwnTool(params));
 }

package/dist/lib/compile.d.ts

@@ -1,5 +1,6 @@
 /**
- * lib/compile.ts — the one YAML → ADK agent-graph compiler.
+ * lib/compile.ts — the one YAML → agent compiler: a runtime-neutral
+ * AgentSpec, and the ADK agent graph built from it.
  *
  * WHY this file exists:
  *   The A2A server carried this logic as two closures inside its executor,
@@ -26,11 +27,20 @@
  * paths build subagents through the same function, so the agent a route
  * dispatches to is identical to the one DELEGATE would have wrapped.
  * Contract and rationale: lib/dispatch.ts.
+ *
+ * ── One spec, two runtimes (ADR 0073) ─────────────────────────────────────
+ * compileSpec and compileSubagentSpec do the work every runtime shares:
+ * resolve and gate the tools, append the skills index, resolve the model
+ * once, build the generateContentConfig. The result is an AgentSpec.
+ * lib/compileAdk.ts builds ADK's LlmAgent from it (compileGraph and
+ * compileSubagent are spec + compileAdk), and lib/compileNative.ts builds
+ * the native loop's NativeAgent (ADR 0045). runSyndicateTurn picks one by
+ * MELCHIZEDEK_RUNTIME or its `runtime` option.
  */
-import { FunctionTool, LlmAgent } from '@google/adk';
-import type { BaseTool } from '@google/adk';
-import type { BaseLlm } from '@google/adk';
-import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+import { BaseLlm, FunctionTool } from '@google/adk';
+import type { BaseTool, LlmAgent } from '@google/adk';
+import type { ReasoningSetting, SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+import type { ExampleConfig } from './tools/examples.ts';
 import type { SkillsConfig } from './tools/skillToolset.ts';
 export interface CompileOptions {
     /**
@@ -57,16 +67,22 @@ export interface CompileOptions {
      */
     nodeConfig?: (agentName: string) => Record<string, unknown> | undefined;
 }
-/** An agent's `context:` block: compact a long conversation into a summary (ADR 0033). */
-export interface ContextConfig {
-    /** Compact when the last request's prompt passed this many tokens. */
-    compact_after_tokens: number;
-    /** Events kept verbatim after the summary. Default 6. */
-    keep_recent_events?: number;
-    /** The model that writes the summary. Default: the agent's own. */
-    summary_model?: string;
-}
-export declare const DEFAULT_KEEP_RECENT_EVENTS = 6;
+export { REASONING_BUDGETS, reasoningConfig } from './models/reasoning.ts';
+/**
+ * An agent's generateContentConfig with its `reasoning:` key mapped in for
+ * the model it runs on. Unchanged (the same object) when the agent sets no
+ * `reasoning`. The loader refuses `reasoning` next to the older spelling;
+ * this refuses it too, for a config built in code.
+ */
+export declare function withReasoning(agent: {
+    name?: string;
+    reasoning?: ReasoningSetting;
+    generateContentConfig?: object;
+}, model: string | undefined): Record<string, unknown> | undefined;
+/** An agent's `context:` block and its default, owned by the native compactor (ADR 0033); compileAdk hands the same values to ADK's. */
+export type { ContextConfig } from './runtime/native/compaction.ts';
+import type { ContextConfig } from './runtime/native/compaction.ts';
+export { DEFAULT_KEEP_RECENT_EVENTS } from './runtime/native/compaction.ts';
 /**
  * A copy of a FunctionTool that runs only after a person approves the call
  * (ADR 0028). ADK's own gate does the work: the call raises an
@@ -76,21 +92,23 @@ export declare const DEFAULT_KEEP_RECENT_EVENTS = 6;
  */
 export declare function requireApprovalOn(tool: FunctionTool): FunctionTool;
 /**
- * A copy of an OpenAPI tool (lib/tools/openapiTools.ts) that runs only after
- * a person approves the call: the same confirmation interrupt FunctionTool's
- * own gate raises, so the turn pauses and resumes exactly as ADR 0028 says.
+ * A copy of an ADK BaseTool that runs only after a person approves the
+ * call: the same confirmation interrupt FunctionTool's own gate raises, so
+ * the turn pauses and resumes exactly as ADR 0028 says. The engine no
+ * longer uses it: an OpenAPI operation is a FunctionTool over an own Tool
+ * (ADR 0067) and takes requireApprovalOn like every registry tool.
+ * @deprecated Gate a FunctionTool with requireApprovalOn, or an own Tool
+ * with requireApproval (lib/tools/tool.ts).
  */
 export declare function requireApprovalOnBaseTool<T extends BaseTool>(tool: T): T;
 /** True when any agent of a syndicate may pause for approval: a gated tool, or skill scripts. */
 export declare function declaresApprovals(config: SyndicateYamlConfig): boolean;
-/** An agent's `examples:` entry: one exchange the model should imitate. */
-export interface ExampleConfig {
-    input: string;
-    output: string;
-}
+export type { ExampleConfig };
 /**
- * ADK's ExampleTool from YAML pairs: never called by the model, it adds the
- * exchanges to every request's instruction as few-shot examples.
+ * An agent's `examples:` as the ADK tool for their InstructionTool
+ * (lib/tools/examples.ts): never called by the model, it adds the exchanges
+ * to every request's instruction as few-shot examples, in the words ADK's
+ * ExampleTool used.
  */
 export declare function examplesTool(examples: ExampleConfig[] | undefined): unknown[];
 /** True when a turn running this agent directly may pause for a person (ADR 0028). */
@@ -99,15 +117,87 @@ export declare function agentGates(agent: {
     skills?: SkillsConfig;
 } | undefined): boolean;
 /**
- * Builds ONE runnable agent from a subagent entry. A `yaml_reference` entry
- * compiles the nested syndicate's whole graph under this entry's name and
+ * One entry of an agent's tool list, in the order the model sees it.
+ * `tool` is a resolved tool as the registry gives it: during the dual
+ * period an ADK object that carries its own Tool or InstructionTool
+ * (lib/tools/adkTool.ts), an MCP tool or the skills toolset, gated by
+ * require_approval where the YAML says so. `agent` is a delegated subagent
+ * (DELEGATE mode), `remote` a subagent served over A2A.
+ */
+export type SpecTool = {
+    kind: 'tool';
+    tool: unknown;
+} | {
+    kind: 'agent';
+    agent: AgentSpec;
+} | {
+    kind: 'remote';
+    name: string;
+    description: string;
+    url: string;
+};
+/**
+ * One YAML agent, compiled, for either runtime: what lib/compileAdk.ts
+ * turns into ADK's LlmAgent and lib/compileNative.ts into the native loop's
+ * NativeAgent. Built once per agent by compileSpec and compileSubagentSpec:
+ * the tools resolved (OpenAPI operations built, MCP tools listed) and
+ * gated, the skills index appended to the instruction, the model resolved
+ * once through CompileOptions.resolveModel, and the generateContentConfig
+ * built for the model the agent runs on.
+ */
+export interface AgentSpec {
+    name: string;
+    description?: string;
+    /** The model id the YAML names; undefined when the agent takes the resolver's default. */
+    model?: string;
+    /** What CompileOptions.resolveModel returned for `model`: an id, or an adapter instance (a BYOK one on the A2A server). */
+    resolvedModel?: unknown;
+    /** The id the agent runs on: the YAML's, else the resolved adapter's. */
+    modelId?: string;
+    /** `fallback_model:`, unresolved: each runtime resolves it where it calls it. */
+    fallbackModel?: string;
+    /** The YAML instruction, with the skills index appended when the agent has `skills:`. */
+    instruction: string;
+    globalInstruction?: string;
+    tools: SpecTool[];
+    outputSchema?: Record<string, unknown>;
+    /** The YAML's config with `reasoning:` mapped in and server-side tool invocations on, as both runtimes send it. */
+    generateContentConfig: Record<string, unknown>;
+    includeContents?: 'default' | 'none';
+    outputKey?: string;
+    disallowTransferToParent?: boolean;
+    disallowTransferToPeers?: boolean;
+    /** `code_execution: gemini`. */
+    codeExecution?: 'gemini';
+    /** `context:`: compaction (ADR 0033). */
+    context?: ContextConfig;
+    /** `mode: task`. */
+    mode?: 'task';
+}
+/**
+ * The spec of ONE agent from a subagent entry. A `yaml_reference` entry is
+ * the nested syndicate's whole graph under this entry's name and
  * description, so the parent sees one tool (or one route) either way.
  */
+export declare function compileSubagentSpec(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<AgentSpec>;
+/**
+ * The spec of a syndicate's orchestrator. In DELEGATE mode its subagents
+ * come first among its tools, as delegations; in PLAN-DISPATCH mode it gets
+ * none (ADK refuses outputSchema + AgentTool on one agent — see
+ * config/agents/critic.yaml), and the caller dispatches to a route's own
+ * spec itself.
+ */
+export declare function compileSpec(config: SyndicateYamlConfig, opts?: CompileOptions, overrideName?: string, overrideDescription?: string): Promise<AgentSpec>;
+/**
+ * Builds ONE runnable ADK agent from a subagent entry: its spec, as
+ * lib/compileAdk.ts builds it. A workflow node's settings
+ * (CompileOptions.nodeConfig) apply to a local agent, not to a nested
+ * syndicate's orchestrator.
+ */
 export declare function compileSubagent(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<LlmAgent>;
 /**
- * Compiles a syndicate's orchestrator. In DELEGATE mode its subagents are
- * attached as AgentTools; in PLAN-DISPATCH mode it gets none (ADK refuses
- * outputSchema + AgentTool on one agent — see config/agents/critic.yaml),
- * and the caller dispatches to `compileSubagent(route)` itself.
+ * Compiles a syndicate's orchestrator for the ADK runtime. In DELEGATE mode
+ * its subagents are attached as AgentTools; in PLAN-DISPATCH mode it gets
+ * none, and the caller dispatches to `compileSubagent(route)` itself.
  */
 export declare function compileGraph(config: SyndicateYamlConfig, opts?: CompileOptions, overrideName?: string, overrideDescription?: string): Promise<LlmAgent>;