melchizedek-agents 0.18.0 → 0.20.0

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 './adkPeer.ts';
+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,125 @@ 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, `workflow` a
+ * `yaml_reference` to a workflow syndicate, whose whole graph is the tool
+ * (ADR 0098).
+ */
+export type SpecTool = {
+    kind: 'tool';
+    tool: unknown;
+} | {
+    kind: 'agent';
+    agent: AgentSpec;
+} | {
+    kind: 'remote';
+    name: string;
+    description: string;
+    url: string;
+} | {
+    kind: 'workflow';
+    workflow: WorkflowSpec;
+};
+/**
+ * A workflow syndicate, compiled for either runtime: lib/workflow.ts builds
+ * ADK's Workflow from it, lib/compileNative.ts the native walk's graph and
+ * agents. Nested as a subagent (a `yaml_reference` in DELEGATE mode), the
+ * graph runs under the entry's name and description, and that name is the
+ * root of every node path, as ADK names a Workflow's nodes after it.
+ */
+export interface WorkflowSpec {
+    /** The workflow's name: the syndicate's, or the subagent entry's when nested. */
+    name: string;
+    /** The tool's description when nested; '' at the root. */
+    description: string;
+    /** The syndicate, its `syndicate_name` set to `name`. */
+    config: SyndicateYamlConfig;
+    /** Every agent of the graph, the orchestrator first, as compileSubagentSpec builds it, with its YAML entry. */
+    agents: Array<{
+        yaml: SubagentYamlConfig;
+        spec: AgentSpec;
+    }>;
+    /** The registry entry for a tool node's tool name, or undefined (CompileOptions.onUnknownTool applies). */
+    resolveTool: (name: string) => unknown;
+}
+/**
+ * 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 a workflow syndicate: every agent through compileSubagentSpec
+ * (the orchestrator first, as a node like any other), and the registry's
+ * lookup for its tool nodes. `name` and `description` name a nested one
+ * after its subagent entry (ADR 0098); `ref` is the file it came from.
+ *
+ * A nested workflow runs inside its caller's tool call, so a pause inside it
+ * could not reach the caller (ADR 0028, as for any nested syndicate): an
+ * `ask_user` node is refused by name here, on both runtimes.
+ */
+export declare function compileWorkflowSpec(config: SyndicateYamlConfig, opts?: CompileOptions, name?: string, description?: string, ref?: string): Promise<WorkflowSpec>;
+/**
+ * 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>;