melchizedek-agents 0.16.2 → 0.18.0

package/dist/lib/a2a/executor.js

@@ -19,6 +19,7 @@ import { turnLockKey } from './turnLock.js';
 import { ingestTurnMemory, runSyndicateTurn } from '../runtime/syndicateTurn.js';
 import { approvalResponsePart, describeApproval, pendingApproval } from '../runtime/approvals.js';
 import { declaresApprovals } from '../compile.js';
+import { describeInput } from '../runtime/syndicateTurn.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';
@@ -72,6 +73,9 @@ export function describeFailedTurn(result) {
     if (result.failedStage === 'dispatch' && result.route) {
         return `Error: [${error.code}] ${result.route.route} failed to answer — ${describeTurnError(error)}`;
     }
+    if (result.failedStage === 'workflow') {
+        return `Error: [${error.code}] The workflow failed — ${describeTurnError(error)}`;
+    }
     return `Error: [${error.code}] The agent run failed — ${describeTurnError(error)}`;
 }
 /**
@@ -118,28 +122,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();
@@ -209,6 +249,37 @@ function publishWorking(eventBus, taskId, contextId, text) {
         metadata: undefined,
     }));
 }
+/**
+ * A workflow paused on an `ask_user` node (lib/workflow.ts): the task ends
+ * input-required with the question, and a data part carrying it. The
+ * answer is simply the next message on the conversation; its text becomes
+ * the node's output and the graph resumes where it waited.
+ */
+function publishInputRequest(eventBus, taskId, contextId, input) {
+    const message = statusMessage(taskId, contextId, `Input needed: ${describeInput(input)}`);
+    message.parts.push({
+        content: {
+            $case: 'data',
+            value: {
+                type: 'input_request',
+                interrupt_id: input.id,
+                node: input.node,
+                message: input.message,
+                ...(input.payload !== undefined ? { payload: input.payload } : {}),
+                ...(input.schema !== undefined ? { schema: input.schema } : {}),
+            },
+        },
+        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 turn paused on a gated tool call (ADR 0028): the task ends
  * input-required, saying what is to be approved, with a data part a client
@@ -332,6 +403,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;
@@ -347,6 +420,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,
@@ -360,6 +436,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 {
@@ -408,11 +499,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');
@@ -471,6 +561,10 @@ export class SyndicateExecutor {
                     taskId,
                     configHash: this.configHashFor(),
                     attributes: surfaceAttributes(ctx),
+                    traceparent: ctx.traceparent,
+                    onSpanStart: (ids) => {
+                        traceId = ids.traceId;
+                    },
                 },
                 events: {
                     onProgress: (text) => publishWorking(eventBus, taskId, contextId, text),
@@ -497,6 +591,12 @@ export class SyndicateExecutor {
                 await report(ctx, 'input-required', 'approval', 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);
+                await report(ctx, 'input-required', 'input', u);
+                return;
+            }
             if (result.status === 'failed') {
                 warn(`✗ Task ${short} failed [${result.error?.code}] after ${spent}`);
                 publishFinal(eventBus, taskId, contextId, 'failed', describeFailedTurn(result));

package/dist/lib/compile.d.ts

@@ -27,9 +27,10 @@
  * dispatches to is identical to the one DELEGATE would have wrapped.
  * Contract and rationale: lib/dispatch.ts.
  */
-import { FunctionTool, LlmAgent } from '@google/adk';
-import type { BaseLlm } from '@google/adk';
+import { BaseLlm, FunctionTool, LlmAgent } from '@google/adk';
+import type { BaseTool } from '@google/adk';
 import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+import type { SkillsConfig } from './tools/skillToolset.ts';
 export interface CompileOptions {
     /**
      * Turns the YAML `model` string into what LlmAgent receives. Default:
@@ -48,7 +49,23 @@ export interface CompileOptions {
     onUnknownTool?: (name: string) => void;
     /** Progress/diagnostic line sink (nested loads, MCP discovery). */
     log?: (message: string) => void;
+    /**
+     * Node settings for an agent compiled as a workflow node (lib/workflow.ts):
+     * ADK's `retryConfig` and `timeout`, which an LlmAgent takes only at
+     * construction. Called with the agent's name; undefined means none.
+     */
+    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;
 /**
  * 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
@@ -57,8 +74,29 @@ export interface CompileOptions {
  * ungated for every other agent that lists the same tool.
  */
 export declare function requireApprovalOn(tool: FunctionTool): FunctionTool;
-/** True when any agent of a syndicate declares an approval gate. */
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * ADK's ExampleTool from YAML pairs: never called by the model, it adds the
+ * exchanges to every request's instruction as few-shot examples.
+ */
+export declare function examplesTool(examples: ExampleConfig[] | undefined): unknown[];
+/** True when a turn running this agent directly may pause for a person (ADR 0028). */
+export declare function agentGates(agent: {
+    require_approval?: string[];
+    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

package/dist/lib/compile.js

@@ -27,13 +27,18 @@
  * dispatches to is identical to the one DELEGATE would have wrapped.
  * Contract and rationale: lib/dispatch.ts.
  */
-import { AgentTool, FunctionTool, LlmAgent } from '@google/adk';
+import { AgentTool, BaseLlm, BuiltInCodeExecutor, ExampleTool, FunctionTool, LLMRegistry, LlmAgent, LlmSummarizer, TokenBasedContextCompactor } from '@google/adk';
+import { relative } from 'node:path';
 import { isDispatchSyndicate } from './dispatch.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
 import { resolveTools as resolveNamedTools } from './toolRegistry.js';
 import { createMcpTools } from './tools/mcpToolFactory.js';
 import { capabilitySummary, describeCapabilities } from './models/capabilities.js';
+import { FallbackLlm } from './models/fallback.js';
+import { resolveModel as resolveRegistryModel } from './models/registry.js';
 import { remoteAgentTool } from './a2a/remoteAgent.js';
+import { buildSkillHarness } from './tools/skillToolset.js';
+import { buildOpenApiTools, isOpenApiTool, namesTool } from './tools/openapiTools.js';
 /** generateContentConfig as every entrypoint has always sent it to ADK. */
 function withServerSideToolInvocations(generateContentConfig) {
     const cfg = (generateContentConfig ?? {});
@@ -68,6 +73,36 @@ function passthroughFields(cfg) {
         out.disallowTransferToPeers = cfg.disallowTransferToPeers;
     return out;
 }
+export const DEFAULT_KEEP_RECENT_EVENTS = 6;
+/**
+ * The LlmAgent fields the engine builds from YAML rather than passing
+ * through (ADR 0033): `code_execution: gemini` (Gemini's server-side
+ * sandbox runs the model's Python; nothing runs on this host), `context:`
+ * (ADK's token-based compactor with an LLM summarizer, so a long
+ * conversation is summarized instead of overflowing the window), and
+ * `mode: task` (the agent works until it calls finish_task; on a workflow
+ * node, its arguments become the node's output).
+ */
+function executionFields(cfg, opts) {
+    const out = {};
+    if (cfg.code_execution === 'gemini')
+        out.codeExecutor = new BuiltInCodeExecutor();
+    if (cfg.mode)
+        out.mode = cfg.mode;
+    if (cfg.context) {
+        const resolve = opts.resolveModel ?? ((m) => m);
+        const summaryModel = resolve(cfg.context.summary_model ?? cfg.model);
+        const llm = typeof summaryModel === 'string' || !summaryModel ? LLMRegistry.newLlm(String(summaryModel ?? cfg.model)) : summaryModel;
+        out.contextCompactors = [
+            new TokenBasedContextCompactor({
+                tokenThreshold: cfg.context.compact_after_tokens,
+                eventRetentionSize: cfg.context.keep_recent_events ?? DEFAULT_KEEP_RECENT_EVENTS,
+                summarizer: new LlmSummarizer({ llm }),
+            }),
+        ];
+    }
+    return out;
+}
 /**
  * Says, once per compiled agent, what its resolved path cannot honour — a
  * dropped server-side tool, a gateway stand-in, or no route at all. Quiet
@@ -95,17 +130,46 @@ export function requireApprovalOn(tool) {
     Object.defineProperty(gated, 'requireConfirmation', { value: true, enumerable: false });
     return gated;
 }
+/**
+ * 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.
+ */
+export function requireApprovalOnBaseTool(tool) {
+    const gated = Object.create(tool);
+    Object.defineProperty(gated, 'runAsync', {
+        value: async (request) => {
+            const ctx = request.toolContext;
+            if (!ctx.toolConfirmation) {
+                ctx.requestConfirmation({ hint: `Approval is required before ${tool.name} runs.`, payload: request.args });
+                ctx.actions.skipSummarization = true;
+                return { error: 'This call requires approval, please approve or reject.' };
+            }
+            if (!ctx.toolConfirmation.confirmed)
+                return { error: 'This call was rejected.' };
+            return tool.runAsync(request);
+        },
+    });
+    return gated;
+}
 function gateTools(tools, names, agentName) {
     if (!names?.length)
         return tools;
     const wanted = new Set(names);
     const out = tools.map((t) => {
-        const name = t?.name;
-        if (!name || !wanted.has(name))
+        const tool = t;
+        const name = tool?.name;
+        if (!name)
+            return t;
+        // An OpenAPI operation may be named as the YAML named it (its operationId).
+        const match = [...wanted].find((w) => w === name || (isOpenApiTool(t) && namesTool(w, { name, operation: tool.operation })));
+        if (!match)
             return t;
-        wanted.delete(name);
+        wanted.delete(match);
+        if (isOpenApiTool(t))
+            return requireApprovalOnBaseTool(t);
         if (!(t instanceof FunctionTool)) {
-            throw new Error(`${agentName}: '${name}' cannot require approval — only function tools from the registry can be gated (ADR 0028).`);
+            throw new Error(`${agentName}: '${name}' cannot require approval — only function tools from the registry and OpenAPI operations can be gated (ADR 0028).`);
         }
         return requireApprovalOn(t);
     });
@@ -116,15 +180,61 @@ function gateTools(tools, names, agentName) {
     }
     return out;
 }
-/** True when any agent of a syndicate declares an approval gate. */
+/** True when any agent of a syndicate may pause for approval: a gated tool, or skill scripts. */
 export function declaresApprovals(config) {
-    return !!config.orchestrator?.require_approval?.length || (config.subagents ?? []).some((s) => !!s.require_approval?.length);
+    return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s));
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts) {
-    const tools = resolveNamedTools(toolNames, opts.onUnknownTool);
+/**
+ * ADK's ExampleTool from YAML pairs: never called by the model, it adds the
+ * exchanges to every request's instruction as few-shot examples.
+ */
+export function examplesTool(examples) {
+    if (!examples?.length)
+        return [];
+    return [
+        new ExampleTool(examples.map((e) => ({ input: { role: 'user', parts: [{ text: e.input }] }, output: [{ role: 'model', parts: [{ text: e.output }] }] }))),
+    ];
+}
+/**
+ * An agent with `fallback_model:` gets its model wrapped (lib/models/fallback.ts):
+ * the fallback answers a provider-side failure, and a provider that keeps
+ * failing is skipped for a cooldown. A model id string is resolved to its
+ * adapter first, so the wrapper always holds two adapters.
+ */
+function withFallback(primary, fallbackId, resolve, opts) {
+    if (!fallbackId)
+        return primary;
+    const asLlm = (m) => (m instanceof BaseLlm ? m : resolveRegistryModel(String(m)));
+    return new FallbackLlm(asLlm(primary), asLlm(resolve(fallbackId)), opts.log ?? ((m) => console.warn(m)));
+}
+async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
+    const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
+    // OpenAPI operations become tools here, so require_approval can name them.
+    for (const entry of openapi ?? []) {
+        const built = await buildOpenApiTools(entry);
+        opts.log?.(`openapi · ${relative(process.cwd(), entry.spec) || entry.spec}: ${built.map((t) => t.name).join(', ') || '(no operations)'}`);
+        for (const t of built) {
+            if (tools.some((existing) => existing?.name === t.name))
+                throw new Error(`openapi ${entry.spec}: tool '${t.name}' collides with another tool; set a prefix`);
+            tools.push(t);
+        }
+    }
     if (mcpServerUrl) {
         opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        const mcpTools = await createMcpTools(mcpServerUrl);
+        const offered = await createMcpTools(mcpServerUrl);
+        // mcp_tools: only the named tools are exposed (a server's list is its
+        // own to change); a name the server does not offer is reported, and a
+        // gate on it fails the compile in gateTools.
+        const allowed = mcpAllowed ? new Set(mcpAllowed) : undefined;
+        const mcpTools = allowed ? offered.filter((t) => allowed.has(t.name)) : offered;
+        if (allowed) {
+            const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
+            if (missing.length)
+                opts.log?.(`MCP ${mcpServerUrl} does not offer ${missing.map((n) => `'${n}'`).join(', ')} (mcp_tools)`);
+            const hidden = offered.length - mcpTools.length;
+            if (hidden)
+                opts.log?.(`MCP ${mcpServerUrl}: ${hidden} tool(s) not in mcp_tools are not exposed`);
+        }
         for (const mcpTool of mcpTools) {
             if (!tools.some((t) => t.name === mcpTool.name))
                 tools.push(mcpTool);
@@ -132,6 +242,28 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts) {
     }
     return tools;
 }
+/**
+ * An agent's `skills:` block becomes one toolset among its tools and one
+ * block appended to its instruction (the frontmatter index, always in view).
+ * The registry tools a skill may unlock (`skills.tools`) are resolved here,
+ * by name, and handed to the toolset; they reach the model only after a
+ * skill naming them is loaded (lib/tools/skillToolset.ts).
+ */
+async function withSkills(instruction, tools, skills, agentName, opts) {
+    if (!skills)
+        return { instruction, tools };
+    const unlockable = resolveNamedTools(skills.tools, opts.onUnknownTool);
+    const harness = await buildSkillHarness(skills, unlockable);
+    const count = Object.keys(harness.skills).length;
+    opts.log?.(`skills · ${agentName}: ${count} skill${count === 1 ? '' : 's'} from ${skills.dir}${skills.scripts === 'local' ? ' · scripts run after approval' : ''}`);
+    for (const problem of harness.problems)
+        opts.log?.(`⚠ skills · ${skills.dir}: not loaded — ${problem}`);
+    return { instruction: `${instruction.trimEnd()}\n\n${harness.instruction}`, tools: [...tools, harness.toolset] };
+}
+/** True when a turn running this agent directly may pause for a person (ADR 0028). */
+export function agentGates(agent) {
+    return !!agent?.require_approval?.length || agent?.skills?.scripts === 'local';
+}
 /**
  * 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
@@ -154,18 +286,21 @@ export async function compileSubagent(subCfg, opts = {}) {
         }
         return compileGraph(nested, opts, subCfg.name, subCfg.description);
     }
-    const tools = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts), subCfg.require_approval, subCfg.name);
+    const gated = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts, subCfg.openapi, subCfg.examples, subCfg.mcp_tools), subCfg.require_approval, subCfg.name);
+    const { instruction, tools } = await withSkills(subCfg.instruction ?? '', gated, subCfg.skills, subCfg.name, opts);
     const resolveModel = opts.resolveModel ?? ((m) => m);
     logCapabilities(opts, subCfg.name, subCfg.model, subCfg.tools);
     return new LlmAgent({
         name: subCfg.name,
         description: subCfg.description,
-        model: resolveModel(subCfg.model),
-        instruction: subCfg.instruction,
+        model: withFallback(resolveModel(subCfg.model), subCfg.fallback_model, resolveModel, opts),
+        instruction,
         tools: tools.length > 0 ? tools : undefined,
         outputSchema: subCfg.outputSchema,
         generateContentConfig: withServerSideToolInvocations(subCfg.generateContentConfig),
         ...passthroughFields(subCfg),
+        ...executionFields(subCfg, opts),
+        ...(opts.nodeConfig?.(subCfg.name) ?? {}),
     });
 }
 /**
@@ -178,6 +313,14 @@ export async function compileGraph(config, opts = {}, overrideName, overrideDesc
     // A registry definition carries its nested syndicates (ADR 0018 item 6).
     if (config.bundled_references && !opts.loadNested)
         opts = { ...opts, loadNested: nestedLoader(config) };
+    // A graph has no orchestrator-with-tools shape to build: its agents are
+    // nodes (lib/workflow.ts). Nested as a yaml_reference, only its
+    // orchestrator runs, since ADK cannot yet make a Workflow a subagent.
+    if (config.workflow && !overrideName) {
+        throw new Error(`${config.syndicate_name}: a workflow syndicate is compiled with compileWorkflow (lib/workflow.ts), not compileGraph`);
+    }
+    if (config.workflow)
+        opts.log?.(`${config.syndicate_name}: nested as a subagent, so only its orchestrator runs (a Workflow cannot be a subagent yet)`);
     const compiledTools = isDispatchSyndicate(config)
         ? []
         : await Promise.all((config.subagents ?? []).map(async (subCfg) => {
@@ -190,17 +333,19 @@ export async function compileGraph(config, opts = {}, overrideName, overrideDesc
     // Orchestrator tools are registry names only — no entrypoint has ever
     // attached an MCP server to an orchestrator, and this compiler preserves
     // that exactly rather than widening the contract in passing.
-    compiledTools.push(...gateTools(await resolveAgentTools(config.orchestrator.tools, undefined, opts), config.orchestrator.require_approval, overrideName || config.orchestrator.name));
+    compiledTools.push(...gateTools(await resolveAgentTools(config.orchestrator.tools, undefined, opts, config.orchestrator.openapi, config.orchestrator.examples), config.orchestrator.require_approval, overrideName || config.orchestrator.name));
+    const { instruction, tools: orchestratorTools } = await withSkills(config.orchestrator.instruction, compiledTools, config.orchestrator.skills, overrideName || config.orchestrator.name, opts);
     const resolveModel = opts.resolveModel ?? ((m) => m);
     logCapabilities(opts, overrideName || config.orchestrator.name, config.orchestrator.model, config.orchestrator.tools);
     return new LlmAgent({
         name: overrideName || config.orchestrator.name,
         description: overrideDescription || config.orchestrator.description,
-        model: resolveModel(config.orchestrator.model),
-        instruction: config.orchestrator.instruction,
-        tools: compiledTools.length > 0 ? compiledTools : undefined,
+        model: withFallback(resolveModel(config.orchestrator.model), config.orchestrator.fallback_model, resolveModel, opts),
+        instruction,
+        tools: orchestratorTools.length > 0 ? orchestratorTools : undefined,
         outputSchema: config.orchestrator.outputSchema,
         generateContentConfig: withServerSideToolInvocations(config.orchestrator.generateContentConfig),
         ...passthroughFields(config.orchestrator),
+        ...executionFields(config.orchestrator, opts),
     });
 }

package/dist/lib/config.d.ts

@@ -59,6 +59,30 @@ export declare const DEFAULT_GROK_MODEL = "grok-4.7";
  * accept the param and never receive it (lib/models/grokLlm.ts).
  */
 export declare const DEFAULT_GROK_REASONING_EFFORT = "medium";
+/**
+ * Default Moonshot model used when a kimi-* model is requested but no
+ * specific identifier is provided. Requires MOONSHOT_API_KEY
+ * (lib/models/kimiLlm.ts). kimi-k3 is the flagship, priced like a mid-tier
+ * closed model ($3 / $15, Claude Sonnet 4.6's price; Sonnet 5.5 is cheaper);
+ * kimi-k2.6 is the general tier at a quarter of that (the family table and
+ * the cost note are in the adapter's header).
+ */
+export declare const DEFAULT_KIMI_MODEL = "kimi-k3";
+/**
+ * Reasoning effort sent with kimi-k3 requests: 'low' | 'high' | 'max'
+ * (Moonshot's own default is 'max'; K3 always thinks and has no off switch).
+ * Pinned to HIGH — one step below max, which is the benchmark setting and
+ * the slowest; an agent sets generateContentConfig.reasoningEffort to
+ * override. Source: platform.moonshot.ai › Guides › Reasoning effort.
+ */
+export declare const DEFAULT_KIMI_REASONING_EFFORT = "high";
+/**
+ * Model calls one turn may make, subagents included, when the syndicate sets
+ * no `max_steps`. A runaway tool loop stops here instead of at the provider's
+ * bill. Every shipped example that sets a cap sets 12 to 30; a syndicate that
+ * needs more raises its own `max_steps` (ADR 0039).
+ */
+export declare const DEFAULT_MAX_STEPS = 50;
 /**
  * Default open-weight model, served locally by Ollama (lib/models/ollamaLlm.ts).
  * qwen3:8b is the smallest pulled model that supports tool calling — the

package/dist/lib/config.js

@@ -60,6 +60,30 @@ export const DEFAULT_GROK_MODEL = 'grok-4.7';
  * accept the param and never receive it (lib/models/grokLlm.ts).
  */
 export const DEFAULT_GROK_REASONING_EFFORT = 'medium';
+/**
+ * Default Moonshot model used when a kimi-* model is requested but no
+ * specific identifier is provided. Requires MOONSHOT_API_KEY
+ * (lib/models/kimiLlm.ts). kimi-k3 is the flagship, priced like a mid-tier
+ * closed model ($3 / $15, Claude Sonnet 4.6's price; Sonnet 5.5 is cheaper);
+ * kimi-k2.6 is the general tier at a quarter of that (the family table and
+ * the cost note are in the adapter's header).
+ */
+export const DEFAULT_KIMI_MODEL = 'kimi-k3';
+/**
+ * Reasoning effort sent with kimi-k3 requests: 'low' | 'high' | 'max'
+ * (Moonshot's own default is 'max'; K3 always thinks and has no off switch).
+ * Pinned to HIGH — one step below max, which is the benchmark setting and
+ * the slowest; an agent sets generateContentConfig.reasoningEffort to
+ * override. Source: platform.moonshot.ai › Guides › Reasoning effort.
+ */
+export const DEFAULT_KIMI_REASONING_EFFORT = 'high';
+/**
+ * Model calls one turn may make, subagents included, when the syndicate sets
+ * no `max_steps`. A runaway tool loop stops here instead of at the provider's
+ * bill. Every shipped example that sets a cap sets 12 to 30; a syndicate that
+ * needs more raises its own `max_steps` (ADR 0039).
+ */
+export const DEFAULT_MAX_STEPS = 50;
 /**
  * Default open-weight model, served locally by Ollama (lib/models/ollamaLlm.ts).
  * qwen3:8b is the smallest pulled model that supports tool calling — the

package/dist/lib/doctor.js

@@ -84,6 +84,7 @@ export const CONSOLE_URLS = {
     anthropic: 'https://console.anthropic.com',
     openai: 'https://platform.openai.com/api-keys',
     xai: 'https://console.x.ai',
+    moonshot: 'https://platform.moonshot.ai',
     ollama: 'https://ollama.com',
 };
 // ── Discovery ────────────────────────────────────────────────────────────────
@@ -162,8 +163,9 @@ function walk(config, prefix, opts, rows) {
     const orchModel = orch?.model;
     if (orch && orchModel) {
         // In DELEGATE mode the orchestrator calls its subagents as tools; under
-        // plan-dispatch it is a tool-less classifier and code runs the route.
-        const delegates = !config.dispatch && (config.subagents ?? []).length > 0;
+        // plan-dispatch it is a tool-less classifier and code runs the route; in
+        // a workflow it is one node of the graph.
+        const delegates = !config.dispatch && !config.workflow && (config.subagents ?? []).length > 0;
         rows.push({
             agent: prefix + orch.name,
             role: 'orchestrator',
@@ -390,6 +392,15 @@ const ANSI = {
     red: '\x1b[31m',
     cyan: '\x1b[36m',
 };
+/** One id per provider, in that provider's own prefix, for the providers line. */
+const PROBE_ID = {
+    gemini: 'gemini-x',
+    anthropic: 'claude-x',
+    openai: 'gpt-x',
+    xai: 'grok-x',
+    moonshot: 'kimi-x',
+    ollama: 'ollama/x',
+};
 function pad(s, n) {
     return s.length >= n ? s.slice(0, n - 1) + '…' : s.padEnd(n);
 }
@@ -405,9 +416,11 @@ 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('');
-    // Provider line: what is funded, and how.
+    // 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).
     const providerBits = Object.keys(PROVIDERS).map((p) => {
-        const r = describeCapabilities(p === 'ollama' ? 'ollama/x' : p === 'gemini' ? 'gemini-x' : p === 'anthropic' ? 'claude-x' : p === 'openai' ? 'gpt-x' : 'grok-x');
+        const r = describeCapabilities(PROBE_ID[p]);
         const mark = !r.funded ? `${c.red}✗${c.reset}` : r.transport === 'gateway' ? `${c.yellow}◇${c.reset}` : `${c.green}✓${c.reset}`;
         const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : p === 'ollama' ? `${c.dim}local${c.reset}` : `${c.dim}${r.platform ?? 'direct'}${c.reset}`;
         return `${mark} ${PROVIDERS[p].label} ${how}`;

package/dist/lib/index.d.ts

@@ -19,6 +19,8 @@ export type { PendingApproval } from './runtime/approvals.ts';
 export type { DrainedRun, MessagePart, TurnUsage, RouteDecision, SyndicateTurnOptions, SyndicateTurnResult, TraceOptions, TurnEvents, TurnStage, } from './runtime/syndicateTurn.ts';
 export { compileGraph, compileSubagent } from './compile.ts';
 export type { CompileOptions } from './compile.ts';
+export { compileWorkflow, isWorkflowSyndicate, describeInput } from './workflow.ts';
+export type { WorkflowConfig, WorkflowNodeYaml, EdgeElement, PendingInput, CompiledWorkflow } from './workflow.ts';
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.ts';
 export type { A2AApp, A2AAppOptions, RequestIdentity } from './a2a/app.ts';
 export type { A2AContext } from './a2a/executor.ts';