melchizedek-agents 0.9.0

package/dist/lib/config.js

@@ -0,0 +1,110 @@
+/**
+ * lib/config.ts — Framework-level configuration constants.
+ *
+ * WHY this file exists:
+ *   Previously, model identifiers were hardcoded inside individual service
+ *   files, making them invisible to contributors and impossible to change
+ *   without hunting through source.
+ *
+ *   Centralising them here creates a single, obvious place to:
+ *     1. Swap the default inference model used by the A2A server
+ *     2. Change summary/extraction model without touching service logic
+ *     3. Understand the full set of third-party model dependencies at a glance
+ *
+ *   These are intentionally plain constants — not env vars — because model
+ *   IDs are code decisions, not deployment secrets. If you want env-var
+ *   overrides, wrap the const: `process.env.GEMINI_MODEL ?? DEFAULT_GEMINI_MODEL`.
+ */
+// ── Inference Models ──────────────────────────────────────────────────────────
+/**
+ * Default Gemini model used by the A2A server when no model is specified
+ * in the caller's YAML or request.
+ *
+ * Use gemini-3.1-flash-lite for lightweight/cost-efficient loads (subagents,
+ * data retrieval). Use gemini-3.7-flash in YAML for production orchestrators.
+ *
+ * NOTE: gemini-2.5-flash is known incompatible with this framework's
+ * includeServerSideToolInvocations flag on AI Studio Tier 1 — do not use it
+ * as the default. See DOCUMENTATION.md §7.0 for the full compatibility table.
+ *
+ * Supported Gemini identifiers: https://ai.google.dev/gemini-api/docs/models
+ */
+export const DEFAULT_GEMINI_MODEL = 'gemini-3.1-flash-lite';
+/**
+ * Default Claude model used by the A2A server when a claude-* model is
+ * requested but no specific identifier is provided.
+ *
+ * Requires ANTHROPIC_API_KEY to be set. The ClaudeLlm provider in
+ * lib/models/claudeLlm.ts handles routing automatically via LLMRegistry.
+ */
+export const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6';
+/**
+ * Default OpenAI model used when a gpt-* model is requested but no specific
+ * identifier is provided. Requires OPENAI_API_KEY. gpt-5-mini is the
+ * lightweight reasoning tier — enough for subagent work, and it exposes
+ * reasoning summaries via the Responses API (lib/models/gptLlm.ts).
+ */
+export const DEFAULT_GPT_MODEL = 'gpt-5-mini';
+/**
+ * Default xAI model used when a grok-* model is requested but no specific
+ * identifier is provided. Requires XAI_API_KEY (lib/models/grokLlm.ts).
+ * grok-4.5 is a reasoning model (reasoning cannot be disabled); it returns
+ * reasoning summaries, which the adapter surfaces as thinking.
+ */
+export const DEFAULT_GROK_MODEL = 'grok-4.5';
+/**
+ * Reasoning effort sent with grok-4.5 requests: 'low' | 'medium' | 'high'
+ * (xAI's own default is 'high'). Pinned to MEDIUM — deeper than low
+ * without high's latency and token cost. Source: docs.x.ai › Model
+ * capabilities › Text › Reasoning › Effort levels. Older grok ids don't
+ * accept the param and never receive it (lib/models/grokLlm.ts).
+ */
+export const DEFAULT_GROK_REASONING_EFFORT = 'medium';
+/**
+ * Default open-weight model, served locally by Ollama (lib/models/ollamaLlm.ts).
+ * qwen3:8b is the smallest pulled model that supports tool calling — the
+ * floor capability for syndicate delegation. Vision work uses ollama/qwen3-vl:8b.
+ */
+export const DEFAULT_OLLAMA_MODEL = 'ollama/qwen3:8b';
+/**
+ * Model used by SupabaseVectorMemoryService to extract discrete facts
+ * from a session transcript before embedding them.
+ *
+ * Must be a text generation model (not an embedding model).
+ */
+export const MEMORY_EXTRACTION_MODEL = 'gemini-3.7-flash';
+/**
+ * Default model for wiki agent operations (wiki_query, wiki_garden, and the
+ * gap-fill pass in lib/wiki/fill.ts). Prose quality matters more than
+ * latency here, so this sits one tier above the subagent default. Any
+ * provider works — override per call or via WIKI_AGENT_MODEL env
+ * ('claude-*', 'ollama/*', …); routing goes through lib/models/registry.ts.
+ */
+export const WIKI_AGENT_MODEL = 'gemini-3.7-flash';
+// ── Embedding Models ──────────────────────────────────────────────────────────
+/**
+ * Model used by SupabaseVectorMemoryService to produce vector embeddings
+ * for semantic memory storage and retrieval.
+ *
+ * ⚠ IMPORTANT CONSTRAINT: The output dimensionality set below MUST match the
+ * dimensionality of the Supabase pgvector index you have provisioned. The index
+ * is created once and cannot be resized. The default (768) fits within
+ * Supabase's free-tier limits and is compatible with the match_memory_facts
+ * RPC defined in the database schema.
+ *
+ * If you switch embedding models, you must:
+ *   1. Update EMBEDDING_MODEL to the new model identifier.
+ *   2. Update EMBEDDING_DIMENSIONS to match the new model's output.
+ *   3. Drop and recreate your adk_memory_facts table and ivfflat index.
+ *   4. Re-ingest all existing facts (old vectors are dimensionally incompatible).
+ *
+ * Gemini options:
+ *   'gemini-embedding-001'  → supports outputDimensionality up to 3072
+ *   'text-embedding-004'    → supports outputDimensionality up to 768
+ */
+export const EMBEDDING_MODEL = 'gemini-embedding-001';
+/**
+ * Output dimensionality for the embedding model.
+ * Must match the Supabase pgvector index dimension. Default: 768.
+ */
+export const EMBEDDING_DIMENSIONS = 768;

package/dist/lib/dispatch.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Plan-dispatch routing — the second orchestration method.
+ *
+ * ── The two methods ───────────────────────────────────────────────────────
+ * DELEGATE (default, every syndicate without a `dispatch:` block): subagents
+ * are AgentTools. The orchestrator calls one, receives its answer as a tool
+ * response, and must then RE-EMIT that answer as its own text to close the
+ * turn. Classification is implicit in which tool it calls.
+ *
+ * PLAN-DISPATCH (`dispatch:` block present): the orchestrator holds NO
+ * subagent tools at all. It is a pure classifier with an `outputSchema` that
+ * names one route. Code reads that name, selects the matching subagent (or
+ * nested syndicate) and runs it directly — its output IS the task's answer.
+ *
+ * ── Why the second method exists ──────────────────────────────────────────
+ * The relay turn in DELEGATE mode is a whole LLM call whose only job is to
+ * copy text it was explicitly forbidden to edit, and in production it was the
+ * least reliable step in the chain: observed failures included finishing with
+ * zero output tokens (blank reply) and emitting the bare tool name
+ * ("FinancialAnalyst") in place of a 2,599-character answer. PLAN-DISPATCH
+ * removes the failure by construction — there is no relay to fail — and drops
+ * one LLM round-trip per request, since the router now emits ~15 tokens of
+ * JSON instead of re-typing the specialist's whole answer.
+ *
+ * It also makes the hand-off legible: the route is a value in code, so it can
+ * be logged, traced, and streamed to a waiting user as progress. In DELEGATE
+ * mode the choice is only ever implicit in a tool call.
+ *
+ * ── Why the router MUST be tool-less ──────────────────────────────────────
+ * ADK refuses to combine `outputSchema` with agent transfer/AgentTool on the
+ * same agent (see config/agents/critic.yaml — an orchestrator holding both
+ * deadlocks). That constraint is what shapes this design rather than limiting
+ * it: the classifier is a leaf, and dispatch happens in code where it belongs.
+ *
+ * ── Fail-static ───────────────────────────────────────────────────────────
+ * Every failure mode here resolves to `default_route` and answers the user.
+ * A router that returns malformed JSON, an unknown name, an empty string, or
+ * throws outright must never cost the user their reply — the default route is
+ * the one that can answer anything (for the financial router, the full
+ * consultant). Routing is an optimisation; answering is the contract.
+ */
+import type { SyndicateYamlConfig } from './loadSyndicate.ts';
+/** The `dispatch:` block. Its presence switches a syndicate to plan-dispatch. */
+export interface DispatchConfig {
+    /**
+     * Subagent name used whenever routing does not produce a usable answer —
+     * malformed output, an unknown route, or a router that failed outright.
+     * Must name a subagent that can handle ANY input.
+     */
+    default_route: string;
+    /**
+     * Property of the router's JSON holding the chosen route. Default "route".
+     */
+    route_key?: string;
+    /**
+     * Property holding the router's short justification, surfaced as progress
+     * telemetry while the user waits. Default "reason". Optional in the schema.
+     */
+    reason_key?: string;
+    /**
+     * Deterministic pre-classification. Each entry pins a route for messages
+     * whose text matches `pattern`; the first match wins and the classifier
+     * never runs. For facts the message CONTAINS rather than judgments about
+     * what it means — a URL only one specialist can open, an explicit demand
+     * for a named tool. Never for topic guesses: a keyword is not a subject.
+     */
+    route_overrides?: RouteOverride[];
+}
+/** One deterministic routing rule, evaluated against the user's message. */
+export interface RouteOverride {
+    /** Subagent to run on a match. Ignored (with a warning) if undeclared. */
+    route: string;
+    /** JS regular expression source, tested against the raw message text. */
+    pattern: string;
+    /** Regex flags. Default "i". */
+    flags?: string;
+    /** Shown to the waiting user in place of the classifier's `reason`. */
+    reason?: string;
+}
+export interface RouteResolution {
+    /** Name of the subagent to run. Always a real subagent. */
+    route: string;
+    /** The router's stated justification, or '' when it gave none. */
+    reason: string;
+    /** True when routing failed and `default_route` was substituted. */
+    fellBack: boolean;
+    /** Why the fallback happened — for logs. Empty when routing succeeded. */
+    fallbackReason: string;
+    /** True when a `route_overrides` rule pinned this route without a model. */
+    viaOverride: boolean;
+}
+/** True when this syndicate opts into plan-dispatch. */
+export declare function isDispatchSyndicate(config: SyndicateYamlConfig): config is SyndicateYamlConfig & {
+    dispatch: DispatchConfig;
+};
+/**
+ * Turn the router's raw output into a route that definitely exists.
+ *
+ * Pure and synchronous — the whole routing contract is unit-testable offline
+ * (tests/dispatch.test.ts) with no model, no network and no keys.
+ *
+ * @param rawOutput  The router agent's text output (expected: one JSON object)
+ * @param config     The dispatch syndicate's config
+ */
+export declare function resolveRoute(rawOutput: string, config: SyndicateYamlConfig & {
+    dispatch: DispatchConfig;
+}): RouteResolution;
+/**
+ * Deterministic routing, evaluated BEFORE the classifier runs.
+ *
+ * Some routes are decided by what a message CONTAINS, not by what a model
+ * judges it to be about. An x.com link is the motivating case: XScout is the
+ * only route that can open X, so a message carrying one has exactly one
+ * correct destination — yet a flash-lite classifier reading "analyze this
+ * post and tell me if the solution is quantum <link>" saw an analysis
+ * request and chose the consultant, which answered from web knowledge and
+ * said the post could not be read (2026-08-15, twice, with the routing rule
+ * already stating the opposite). Prompt text competes with the rest of the
+ * message; a regex does not.
+ *
+ * Scope discipline: overrides are for facts in the text, never topic
+ * guesses. A misapplied override is worse than a misroute — it cannot be
+ * reasoned around by the classifier at all.
+ *
+ * Pure and synchronous, like resolveRoute. Fail-static: an override naming
+ * an undeclared subagent or carrying an invalid regex is SKIPPED (reported
+ * via `warnings`), leaving normal classification to answer the user.
+ *
+ * @returns the pinned resolution, or null when nothing matched.
+ */
+export declare function matchRouteOverride(messageText: string, config: SyndicateYamlConfig & {
+    dispatch: DispatchConfig;
+}, warnings?: string[]): RouteResolution | null;

package/dist/lib/dispatch.js

@@ -0,0 +1,182 @@
+/**
+ * Plan-dispatch routing — the second orchestration method.
+ *
+ * ── The two methods ───────────────────────────────────────────────────────
+ * DELEGATE (default, every syndicate without a `dispatch:` block): subagents
+ * are AgentTools. The orchestrator calls one, receives its answer as a tool
+ * response, and must then RE-EMIT that answer as its own text to close the
+ * turn. Classification is implicit in which tool it calls.
+ *
+ * PLAN-DISPATCH (`dispatch:` block present): the orchestrator holds NO
+ * subagent tools at all. It is a pure classifier with an `outputSchema` that
+ * names one route. Code reads that name, selects the matching subagent (or
+ * nested syndicate) and runs it directly — its output IS the task's answer.
+ *
+ * ── Why the second method exists ──────────────────────────────────────────
+ * The relay turn in DELEGATE mode is a whole LLM call whose only job is to
+ * copy text it was explicitly forbidden to edit, and in production it was the
+ * least reliable step in the chain: observed failures included finishing with
+ * zero output tokens (blank reply) and emitting the bare tool name
+ * ("FinancialAnalyst") in place of a 2,599-character answer. PLAN-DISPATCH
+ * removes the failure by construction — there is no relay to fail — and drops
+ * one LLM round-trip per request, since the router now emits ~15 tokens of
+ * JSON instead of re-typing the specialist's whole answer.
+ *
+ * It also makes the hand-off legible: the route is a value in code, so it can
+ * be logged, traced, and streamed to a waiting user as progress. In DELEGATE
+ * mode the choice is only ever implicit in a tool call.
+ *
+ * ── Why the router MUST be tool-less ──────────────────────────────────────
+ * ADK refuses to combine `outputSchema` with agent transfer/AgentTool on the
+ * same agent (see config/agents/critic.yaml — an orchestrator holding both
+ * deadlocks). That constraint is what shapes this design rather than limiting
+ * it: the classifier is a leaf, and dispatch happens in code where it belongs.
+ *
+ * ── Fail-static ───────────────────────────────────────────────────────────
+ * Every failure mode here resolves to `default_route` and answers the user.
+ * A router that returns malformed JSON, an unknown name, an empty string, or
+ * throws outright must never cost the user their reply — the default route is
+ * the one that can answer anything (for the financial router, the full
+ * consultant). Routing is an optimisation; answering is the contract.
+ */
+/** True when this syndicate opts into plan-dispatch. */
+export function isDispatchSyndicate(config) {
+    return !!config.dispatch && typeof config.dispatch.default_route === 'string';
+}
+/**
+ * Strip a markdown code fence if the model wrapped its JSON in one.
+ * `responseMimeType: application/json` normally prevents this, but the
+ * resolver stays tolerant so a provider that ignores the hint (or a future
+ * non-Gemini router) degrades to a correct route instead of the default.
+ */
+function unfence(raw) {
+    const trimmed = raw.trim();
+    const fence = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+    return fence ? fence[1].trim() : trimmed;
+}
+/**
+ * Match a model-supplied route name against the declared subagents.
+ * Comparison ignores case and non-alphanumerics, so "financial analyst",
+ * "FinancialAnalyst" and "financial_analyst" all reach the same subagent —
+ * the route is a name the model retypes, and punctuation drift is not a
+ * reason to lose the user's answer.
+ */
+function matchSubagent(candidate, subagents) {
+    const norm = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
+    const target = norm(candidate);
+    if (!target)
+        return undefined;
+    return subagents.find(sub => norm(sub.name) === target);
+}
+/**
+ * Turn the router's raw output into a route that definitely exists.
+ *
+ * Pure and synchronous — the whole routing contract is unit-testable offline
+ * (tests/dispatch.test.ts) with no model, no network and no keys.
+ *
+ * @param rawOutput  The router agent's text output (expected: one JSON object)
+ * @param config     The dispatch syndicate's config
+ */
+export function resolveRoute(rawOutput, config) {
+    const subagents = config.subagents || [];
+    const routeKey = config.dispatch.route_key || 'route';
+    const reasonKey = config.dispatch.reason_key || 'reason';
+    // The default must itself be a real subagent. When it is not, the config is
+    // wrong and the first subagent is the only safe answer left — surfaced as a
+    // fallbackReason so it reaches the logs rather than failing silently.
+    const declaredDefault = matchSubagent(config.dispatch.default_route, subagents);
+    const safeDefault = declaredDefault?.name ?? subagents[0]?.name ?? '';
+    const defaultResolution = (fallbackReason) => ({
+        route: safeDefault,
+        reason: '',
+        fellBack: true,
+        viaOverride: false,
+        fallbackReason: declaredDefault
+            ? fallbackReason
+            : `${fallbackReason}; default_route '${config.dispatch.default_route}' is not a declared subagent`,
+    });
+    if (!rawOutput || !rawOutput.trim()) {
+        return defaultResolution('router returned no output');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(unfence(rawOutput));
+    }
+    catch {
+        return defaultResolution(`router output was not JSON: ${rawOutput.trim().slice(0, 80)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return defaultResolution('router output was not a JSON object');
+    }
+    const record = parsed;
+    const rawRoute = record[routeKey];
+    if (typeof rawRoute !== 'string' || !rawRoute.trim()) {
+        return defaultResolution(`router output has no '${routeKey}' string`);
+    }
+    const matched = matchSubagent(rawRoute, subagents);
+    if (!matched) {
+        return defaultResolution(`router chose unknown route '${rawRoute}'`);
+    }
+    const rawReason = record[reasonKey];
+    return {
+        route: matched.name,
+        reason: typeof rawReason === 'string' ? rawReason.trim() : '',
+        fellBack: false,
+        fallbackReason: '',
+        viaOverride: false,
+    };
+}
+/**
+ * Deterministic routing, evaluated BEFORE the classifier runs.
+ *
+ * Some routes are decided by what a message CONTAINS, not by what a model
+ * judges it to be about. An x.com link is the motivating case: XScout is the
+ * only route that can open X, so a message carrying one has exactly one
+ * correct destination — yet a flash-lite classifier reading "analyze this
+ * post and tell me if the solution is quantum <link>" saw an analysis
+ * request and chose the consultant, which answered from web knowledge and
+ * said the post could not be read (2026-08-15, twice, with the routing rule
+ * already stating the opposite). Prompt text competes with the rest of the
+ * message; a regex does not.
+ *
+ * Scope discipline: overrides are for facts in the text, never topic
+ * guesses. A misapplied override is worse than a misroute — it cannot be
+ * reasoned around by the classifier at all.
+ *
+ * Pure and synchronous, like resolveRoute. Fail-static: an override naming
+ * an undeclared subagent or carrying an invalid regex is SKIPPED (reported
+ * via `warnings`), leaving normal classification to answer the user.
+ *
+ * @returns the pinned resolution, or null when nothing matched.
+ */
+export function matchRouteOverride(messageText, config, warnings) {
+    const overrides = config.dispatch.route_overrides || [];
+    if (!overrides.length || !messageText)
+        return null;
+    const subagents = config.subagents || [];
+    for (const override of overrides) {
+        const matched = matchSubagent(override.route ?? '', subagents);
+        if (!matched) {
+            warnings?.push(`route_overrides: '${override.route}' is not a declared subagent — rule skipped`);
+            continue;
+        }
+        let re;
+        try {
+            re = new RegExp(override.pattern, override.flags ?? 'i');
+        }
+        catch {
+            warnings?.push(`route_overrides: invalid pattern for '${override.route}' — rule skipped`);
+            continue;
+        }
+        if (!re.test(messageText))
+            continue;
+        return {
+            route: matched.name,
+            reason: (override.reason || '').trim(),
+            fellBack: false,
+            fallbackReason: '',
+            viaOverride: true,
+        };
+    }
+    return null;
+}

package/dist/lib/grounding.d.ts

@@ -0,0 +1,28 @@
+/**
+ * lib/grounding.ts — pure helpers for reading native web-search grounding
+ * (Gemini `groundingMetadata`) off ADK events. Grounding is a server-side
+ * tool: it never appears as a function call, so without this a searched
+ * answer and a recalled one are indistinguishable in logs and to clients.
+ * scripts/a2a_server.ts folds these into `[A2A] ⌕ Grounding` log lines and
+ * the `Invoking tool: web_search` / `Web sources: …` status lines that
+ * nihilistic-penguin's RouteTrace renders into the Discord footer.
+ */
+export interface GroundingState {
+    queries: Set<string>;
+    sources: Set<string>;
+}
+export declare function newGroundingState(): GroundingState;
+/** Domain of a grounding chunk: Gemini's `web.title` is already the bare
+ *  domain (its `uri` is an opaque redirect); fall back to the URI's host. */
+export declare function groundingDomain(chunk: any): string | null;
+/**
+ * Fold one event's groundingMetadata into `state`. Returns true when the
+ * event added something new (a query or a source not seen before) — the
+ * caller logs/publishes only then, so a metadata block repeated on every
+ * streaming chunk produces one line, not many.
+ */
+export declare function collectGrounding(event: any, state: GroundingState): boolean;
+/** The `[A2A] ⌕ Grounding: …` log line body. */
+export declare function describeGrounding(state: GroundingState, maxSources?: number): string;
+/** The consumer contract line (penguin RouteTrace `_SOURCES_RE`), or null. */
+export declare function webSourcesLine(state: GroundingState, max?: number): string | null;

package/dist/lib/grounding.js

@@ -0,0 +1,61 @@
+/**
+ * lib/grounding.ts — pure helpers for reading native web-search grounding
+ * (Gemini `groundingMetadata`) off ADK events. Grounding is a server-side
+ * tool: it never appears as a function call, so without this a searched
+ * answer and a recalled one are indistinguishable in logs and to clients.
+ * scripts/a2a_server.ts folds these into `[A2A] ⌕ Grounding` log lines and
+ * the `Invoking tool: web_search` / `Web sources: …` status lines that
+ * nihilistic-penguin's RouteTrace renders into the Discord footer.
+ */
+export function newGroundingState() {
+    return { queries: new Set(), sources: new Set() };
+}
+/** Domain of a grounding chunk: Gemini's `web.title` is already the bare
+ *  domain (its `uri` is an opaque redirect); fall back to the URI's host. */
+export function groundingDomain(chunk) {
+    const title = chunk?.web?.title;
+    if (title && /^[a-z0-9.-]+\.[a-z]{2,}$/i.test(title))
+        return title.toLowerCase();
+    const uri = chunk?.web?.uri;
+    if (uri) {
+        try {
+            return new URL(uri).hostname.replace(/^www\./, '');
+        }
+        catch { /* opaque */ }
+    }
+    return title || null;
+}
+/**
+ * Fold one event's groundingMetadata into `state`. Returns true when the
+ * event added something new (a query or a source not seen before) — the
+ * caller logs/publishes only then, so a metadata block repeated on every
+ * streaming chunk produces one line, not many.
+ */
+export function collectGrounding(event, state) {
+    const gm = event?.groundingMetadata;
+    if (!gm)
+        return false;
+    const before = state.queries.size + state.sources.size;
+    for (const q of gm.webSearchQueries ?? []) {
+        if (typeof q === 'string' && q.trim())
+            state.queries.add(q.trim());
+    }
+    for (const c of gm.groundingChunks ?? []) {
+        const d = groundingDomain(c);
+        if (d)
+            state.sources.add(d);
+    }
+    return state.queries.size + state.sources.size > before;
+}
+/** The `[A2A] ⌕ Grounding: …` log line body. */
+export function describeGrounding(state, maxSources = 8) {
+    const q = state.queries.size, s = state.sources.size;
+    const list = s ? ` (${[...state.sources].slice(0, maxSources).join(', ')})` : '';
+    return `${q} quer${q === 1 ? 'y' : 'ies'} · ${s} source${s === 1 ? '' : 's'}${list}`;
+}
+/** The consumer contract line (penguin RouteTrace `_SOURCES_RE`), or null. */
+export function webSourcesLine(state, max = 10) {
+    if (!state.sources.size)
+        return null;
+    return `Web sources: ${[...state.sources].slice(0, max).join(', ')}`;
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * lib/index.ts — the package's main entry (public repo only).
+ *
+ * This barrel IS the primary API surface of the `melchizedek-agents`
+ * package: what it re-exports is covered by semver; everything else is
+ * reachable only through the subpath exports declared in package.json.
+ * The cloned repo's npm scripts never import this file — they run the
+ * modules directly.
+ */
+export { loadSyndicate, loadSyndicateFromRegistry, parseCliBindings, validateRegistryConfig, } from './loadSyndicate.ts';
+export type { AgentYamlConfig, LoadSyndicateOptions, SubagentYamlConfig, SyndicateYamlConfig, VariableMap, } from './loadSyndicate.ts';
+export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, registerAvailableProviders, resolveModel, } from './models/registry.ts';
+export { resolveTools } from './toolRegistry.ts';
+export { loadEnv } from './loadEnv.ts';

package/dist/lib/index.js

@@ -0,0 +1,13 @@
+/**
+ * lib/index.ts — the package's main entry (public repo only).
+ *
+ * This barrel IS the primary API surface of the `melchizedek-agents`
+ * package: what it re-exports is covered by semver; everything else is
+ * reachable only through the subpath exports declared in package.json.
+ * The cloned repo's npm scripts never import this file — they run the
+ * modules directly.
+ */
+export { loadSyndicate, loadSyndicateFromRegistry, parseCliBindings, validateRegistryConfig, } from "./loadSyndicate.js";
+export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, registerAvailableProviders, resolveModel, } from "./models/registry.js";
+export { resolveTools } from "./toolRegistry.js";
+export { loadEnv } from "./loadEnv.js";

package/dist/lib/loadEnv.d.ts

@@ -0,0 +1,21 @@
+/**
+ * lib/loadEnv.ts — minimal, dependency-free .env loader.
+ *
+ * WHY this exists:
+ *   The project runs via `node --experimental-strip-types` and intentionally
+ *   avoids a runtime dependency on `dotenv`. Several scripts previously did
+ *   `import 'dotenv/config'`, which throws because `dotenv` is not installed.
+ *   This shared helper replicates the same parse used inline by a2a_server.ts
+ *   and syndicate_chat.ts, so every entrypoint loads `.env` the same way.
+ *
+ * Existing process.env values always win — the file only fills in what's unset.
+ */
+/**
+ * Populate process.env from the repo-root `.env` file.
+ *
+ * @param moduleUrl Pass `import.meta.url` from any entrypoint script; the
+ *   repo root is found by walking up from the script to the nearest
+ *   directory containing `package.json`, so scripts may live at any depth
+ *   under `scripts/`. When omitted, `process.cwd()` is used.
+ */
+export declare function loadEnv(moduleUrl?: string): void;

package/dist/lib/loadEnv.js

@@ -0,0 +1,58 @@
+/**
+ * lib/loadEnv.ts — minimal, dependency-free .env loader.
+ *
+ * WHY this exists:
+ *   The project runs via `node --experimental-strip-types` and intentionally
+ *   avoids a runtime dependency on `dotenv`. Several scripts previously did
+ *   `import 'dotenv/config'`, which throws because `dotenv` is not installed.
+ *   This shared helper replicates the same parse used inline by a2a_server.ts
+ *   and syndicate_chat.ts, so every entrypoint loads `.env` the same way.
+ *
+ * Existing process.env values always win — the file only fills in what's unset.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Populate process.env from the repo-root `.env` file.
+ *
+ * @param moduleUrl Pass `import.meta.url` from any entrypoint script; the
+ *   repo root is found by walking up from the script to the nearest
+ *   directory containing `package.json`, so scripts may live at any depth
+ *   under `scripts/`. When omitted, `process.cwd()` is used.
+ */
+export function loadEnv(moduleUrl) {
+    try {
+        const root = moduleUrl
+            ? findRepoRoot(dirname(fileURLToPath(moduleUrl)))
+            : process.cwd();
+        const raw = readFileSync(join(root, '.env'), 'utf-8');
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const eq = trimmed.indexOf('=');
+            if (eq === -1)
+                continue;
+            const key = trimmed.slice(0, eq).trim();
+            const val = trimmed.slice(eq + 1).trim();
+            if (!process.env[key])
+                process.env[key] = val;
+        }
+    }
+    catch {
+        // .env not present — rely on the ambient environment.
+    }
+}
+/** Nearest ancestor of `dir` containing package.json; `dir` itself if none. */
+function findRepoRoot(dir) {
+    let current = dir;
+    while (true) {
+        if (existsSync(join(current, 'package.json')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return dir;
+        current = parent;
+    }
+}