melchizedek-agents 0.18.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';
@@ -303,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
@@ -375,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() {
@@ -531,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) {
@@ -551,11 +603,12 @@ 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,
@@ -591,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);
@@ -609,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,10 +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 { BaseLlm, FunctionTool, LlmAgent } from '@google/adk';
-import type { BaseTool } 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 {
     /**
@@ -56,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
@@ -75,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). */
@@ -98,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>;