melchizedek-agents 0.9.0

package/dist/lib/loadSyndicate.d.ts

@@ -0,0 +1,177 @@
+import type { DispatchConfig } from './dispatch.ts';
+export type { DispatchConfig } from './dispatch.ts';
+export interface ThinkingConfig {
+    /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
+    thinkingBudget?: number;
+    /** Stream the thinking trace in the response. */
+    includeThoughts?: boolean;
+}
+export interface SafetySetting {
+    category: string;
+    threshold: string;
+}
+/**
+ * Maps to GenerateContentConfig from @google/genai.
+ * Controls model sampling and generation behaviour.
+ * ⚠ Do NOT set `tools` here — use the top-level `tools` field on the agent.
+ * ⚠ Do NOT set `thinkingConfig` via the tools param — use this block.
+ */
+export interface GenerateContentConfig {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    maxOutputTokens?: number;
+    stopSequences?: string[];
+    candidateCount?: number;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    seed?: number;
+    responseMimeType?: string;
+    safetySettings?: SafetySetting[];
+    thinkingConfig?: ThinkingConfig;
+}
+/**
+ * Maps to LlmAgentConfig (+ BaseAgentConfig) from @google/adk.
+ */
+export interface AgentYamlConfig {
+    /** Unique agent name. Must be a valid JS identifier. Cannot be "user". */
+    name: string;
+    /** One-line description used by other agents to decide when to delegate here. */
+    description?: string;
+    /** Gemini model identifier. Subagents inherit this if not set. */
+    model: string;
+    /** System prompt / persona. Maps to LlmAgentConfig.instruction. */
+    instruction: string;
+    /**
+     * Global instruction applied to ALL agents in the tree.
+     * Only the root agent's value takes effect.
+     */
+    globalInstruction?: string;
+    /**
+     * Named built-in tools to attach to this agent.
+     * Supported: "google_search", "code_execution"
+     * Maps to LlmAgentConfig.tools[].
+     */
+    tools?: string[];
+    /**
+     * Whether conversation history is included in model requests.
+     * "default" = stateful, "none" = stateless.
+     * Maps to LlmAgentConfig.includeContents.
+     */
+    includeContents?: 'default' | 'none';
+    /** Prevents LLM from transferring control back to parent agent. */
+    disallowTransferToParent?: boolean;
+    /** Prevents LLM from transferring control to peer agents. */
+    disallowTransferToPeers?: boolean;
+    /**
+     * Saves final reply to session state under this key.
+     * Useful for chaining agents.
+     */
+    outputKey?: string;
+    /**
+     * Model generation config (temperature, topP, safety, thinking, etc.)
+     * Maps to LlmAgentConfig.generateContentConfig.
+     */
+    generateContentConfig?: GenerateContentConfig;
+    /**
+     * Output schema for structured JSON responses.
+     * Maps to LlmAgentConfig.outputSchema.
+     */
+    outputSchema?: Record<string, unknown>;
+    mcp_server_url?: string;
+    orchestration?: {
+        role?: 'primary' | 'sub-agent';
+        delegates?: string[];
+    };
+}
+export interface SubagentYamlConfig extends Partial<AgentYamlConfig> {
+    /** Required when used as AgentTool — orchestrator reads this to delegate. */
+    name: string;
+    description: string;
+    yaml_reference?: string;
+}
+export type VariableMap = Record<string, string | number | boolean>;
+export interface SyndicateYamlConfig {
+    syndicate_name: string;
+    orchestrator: AgentYamlConfig;
+    subagents: SubagentYamlConfig[];
+    /**
+     * Opts this syndicate into PLAN-DISPATCH orchestration: the orchestrator is
+     * a tool-less classifier whose `outputSchema` names one route, and code runs
+     * that subagent directly so its output is the answer — no relay turn.
+     * Absent = classic DELEGATE mode (subagents as AgentTools).
+     * See lib/dispatch.ts for the full contract.
+     */
+    dispatch?: DispatchConfig;
+    /** Optional default variable definitions for {{token}} interpolation. */
+    variables?: VariableMap;
+    /** Defines the persistence and semantic memory layer for the syndicate. */
+    memory_system?: 'internal-only' | 'session-only' | 'long-term';
+    /**
+     * Domain rules appended to the shared fact-extraction prompt for THIS
+     * syndicate only. The prompt is global (every long-term memory consumer
+     * shares it), so anything domain-specific — "never store a market quote" —
+     * belongs here rather than edited into the prompt itself.
+     * Read by the A2A server at ingestion time; ignored without `long-term`.
+     */
+    memory_extraction_rules?: string;
+    /** Optional hard technical limit for maximum ADK runner loops (LLM -> Tool cycles). */
+    max_steps?: number;
+}
+/**
+ * Options for `loadSyndicate()`.
+ */
+export interface LoadSyndicateOptions {
+    /** Variable bindings that resolve `{{token}}` placeholders in the YAML. */
+    bindings?: VariableMap;
+    /**
+     * Direct property overrides applied after binding interpolation.
+     */
+    overrides?: Partial<SyndicateYamlConfig>;
+    /**
+     * Root directory the loader is jailed to. Resolution order:
+     * this option → `MELCHIZEDEK_AGENTS_DIR` env → `<cwd>/config/agents`.
+     * Lets a consumer repo keep its syndicates anywhere (the engine is a
+     * package, not a place). NOTE: nested `yaml_reference:` loads made by
+     * callers that don't thread options through resolve via env/default,
+     * so a non-default root is best set process-wide via the env var.
+     */
+    agentsDir?: string;
+}
+/**
+ * Parse CLI variable bindings into a VariableMap.
+ *
+ * Supports two formats:
+ *   --bindings '{"focus_area": "AI Regulation", "headline_count": 10}'
+ *   --bind key=value  (individual overrides, take priority over --bindings)
+ */
+export declare function parseCliBindings(argv: string[]): VariableMap;
+/**
+ * Load and fully resolve a syndicate YAML definition.
+ *
+ * @param filename  YAML filename inside `config/agents/`. Production
+ *   syndicates live at the root; the shipped starter-pack examples live in
+ *   `config/agents/examples/`. A bare filename is resolved against the root
+ *   first, then `examples/`, so callers (and nested `yaml_reference`s) never
+ *   need to know which side of the split a file is on.
+ * @param options   Bindings and optional overrides
+ *
+ * @example
+ * ```typescript
+ * const config = loadSyndicate('syndicate.yaml', {
+ *   bindings: { headline_count: 10 },
+ *   overrides: { syndicate_name: 'Custom Council' },
+ * });
+ * ```
+ */
+export declare function loadSyndicate(filename: string, options?: LoadSyndicateOptions): SyndicateYamlConfig;
+/**
+ * Validates registry configurations against strict ADK and project constraints.
+ */
+export declare function validateRegistryConfig(config: Record<string, any>): void;
+/**
+ * Loads a syndicate configuration from the Supabase registry.
+ * @param registryId The document ID in the adk_agent_registry table
+ * @param options Load options (bindings and overrides)
+ */
+export declare function loadSyndicateFromRegistry(registryId: string, options?: LoadSyndicateOptions): Promise<SyndicateYamlConfig>;

package/dist/lib/loadSyndicate.js

@@ -0,0 +1,264 @@
+import { parse } from 'yaml';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createClient } from '@supabase/supabase-js';
+import { hasSupabaseCredentials } from "./persistence/supabaseProvider.js";
+// ── Variable Injection (private) ──────────────────────────
+const TOKEN_RE = /\{\{(\w+)\}\}/g;
+const FULL_TOKEN_RE = /^\{\{(\w+)\}\}$/;
+function interpolateString(value, vars) {
+    const fullMatch = value.match(FULL_TOKEN_RE);
+    if (fullMatch) {
+        const key = fullMatch[1];
+        if (key in vars)
+            return vars[key];
+        return value;
+    }
+    return value.replace(TOKEN_RE, (_match, key) => {
+        if (key in vars)
+            return String(vars[key]);
+        return _match;
+    });
+}
+function interpolateDeep(obj, vars) {
+    if (typeof obj === 'string') {
+        return interpolateString(obj, vars);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => interpolateDeep(item, vars));
+    }
+    if (obj !== null && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = interpolateDeep(value, vars);
+        }
+        return result;
+    }
+    return obj;
+}
+function findUnresolvedTokens(obj) {
+    const tokens = new Set();
+    function walk(val) {
+        if (typeof val === 'string') {
+            let m;
+            TOKEN_RE.lastIndex = 0;
+            while ((m = TOKEN_RE.exec(val)) !== null) {
+                tokens.add(m[1]);
+            }
+        }
+        else if (Array.isArray(val)) {
+            val.forEach(walk);
+        }
+        else if (val !== null && typeof val === 'object') {
+            Object.values(val).forEach(walk);
+        }
+    }
+    walk(obj);
+    return [...tokens];
+}
+function applyOverrides(config, overrides) {
+    return { ...config, ...overrides };
+}
+/**
+ * Bindings every load starts from, resolved at load time so date-anchored
+ * prompts never ship a stale hardcoded date. YAML `variables` and caller
+ * `bindings` both take precedence.
+ */
+function defaultBindings() {
+    return {
+        current_date: new Date().toLocaleDateString('en-US', {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            timeZone: 'America/New_York',
+        }),
+    };
+}
+// ── CLI Binding Parser ────────────────────────────────────
+function coerce(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    const num = Number(raw);
+    if (!isNaN(num) && raw !== '')
+        return num;
+    return raw;
+}
+/**
+ * Parse CLI variable bindings into a VariableMap.
+ *
+ * Supports two formats:
+ *   --bindings '{"focus_area": "AI Regulation", "headline_count": 10}'
+ *   --bind key=value  (individual overrides, take priority over --bindings)
+ */
+export function parseCliBindings(argv) {
+    let vars = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--bindings' && i + 1 < argv.length) {
+            try {
+                const parsed = JSON.parse(argv[i + 1]);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    for (const [key, val] of Object.entries(parsed)) {
+                        if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+                            vars[key] = val;
+                        }
+                    }
+                }
+            }
+            catch {
+                console.warn(`⚠ Failed to parse --bindings JSON: ${argv[i + 1]}`);
+            }
+            i++;
+            continue;
+        }
+        if (argv[i] === '--bind' && i + 1 < argv.length) {
+            const pair = argv[i + 1];
+            const eq = pair.indexOf('=');
+            if (eq === -1)
+                continue;
+            const key = pair.slice(0, eq).trim();
+            const raw = pair.slice(eq + 1).trim();
+            vars[key] = coerce(raw);
+            i++;
+        }
+    }
+    return vars;
+}
+// ── Primary Entrypoint ────────────────────────────────────
+/**
+ * Load and fully resolve a syndicate YAML definition.
+ *
+ * @param filename  YAML filename inside `config/agents/`. Production
+ *   syndicates live at the root; the shipped starter-pack examples live in
+ *   `config/agents/examples/`. A bare filename is resolved against the root
+ *   first, then `examples/`, so callers (and nested `yaml_reference`s) never
+ *   need to know which side of the split a file is on.
+ * @param options   Bindings and optional overrides
+ *
+ * @example
+ * ```typescript
+ * const config = loadSyndicate('syndicate.yaml', {
+ *   bindings: { headline_count: 10 },
+ *   overrides: { syndicate_name: 'Custom Council' },
+ * });
+ * ```
+ */
+export function loadSyndicate(filename, options = {}) {
+    const { bindings = {}, overrides } = options;
+    // Security: confine reads to the agents root. `filename` can originate from
+    // a network-controlled path segment (see a2a_server dynamic routes), so we
+    // must reject any value that resolves outside that root (e.g. "../../.env").
+    // The root itself is trusted configuration: option → env → cwd default.
+    const agentsDir = path.resolve(options.agentsDir ??
+        process.env.MELCHIZEDEK_AGENTS_DIR ??
+        path.join(process.cwd(), 'config', 'agents'));
+    let filePath = path.resolve(agentsDir, filename);
+    if (filePath !== agentsDir && !filePath.startsWith(agentsDir + path.sep)) {
+        throw new Error(`Invalid syndicate path: '${filename}' resolves outside the agents directory`);
+    }
+    // Starter-pack fallback: a name not found at the root is looked up in
+    // examples/ (still inside the jail), so moving a YAML between the two
+    // never breaks a bare-id A2A route or an npm script.
+    if (!fs.existsSync(filePath)) {
+        const inExamples = path.resolve(agentsDir, 'examples', filename);
+        if (inExamples.startsWith(agentsDir + path.sep) && fs.existsSync(inExamples)) {
+            filePath = inExamples;
+        }
+    }
+    const fileContent = fs.readFileSync(filePath, 'utf-8');
+    const raw = parse(fileContent);
+    const merged = {
+        ...defaultBindings(),
+        ...(raw.variables ?? {}),
+        ...bindings,
+    };
+    const hasVars = Object.keys(merged).length > 0;
+    const interpolated = hasVars ? interpolateDeep(raw, merged) : raw;
+    if (hasVars) {
+        const unresolved = findUnresolvedTokens(interpolated);
+        if (unresolved.length > 0) {
+            console.warn(`⚠ Unresolved template variables: ${unresolved.map(t => `{{${t}}}`).join(', ')}`);
+        }
+    }
+    const { variables: _stripped, ...clean } = interpolated;
+    let config = clean;
+    if (overrides) {
+        config = applyOverrides(config, overrides);
+    }
+    return config;
+}
+// ── Registry Validation (Step 7) ──────────────────────────
+const VALID_SYSTEM_TOOLS = [
+    'google_search',
+    'generate_image',
+    'load_memory',
+    'preload_memory',
+    'get_company_fundamentals',
+    'get_macro_metrics',
+    'get_technical_indicators'
+];
+/**
+ * Validates registry configurations against strict ADK and project constraints.
+ */
+export function validateRegistryConfig(config) {
+    // 1. Enforce native property mapping rules
+    if ('options' in config) {
+        throw new Error(`[Validation Error] Legacy 'options' object found. Model parameters must reside in 'generateContentConfig'.`);
+    }
+    // 2. Validate declared tool references (Relaxed for MCP compatibility)
+    // We no longer strictly validate against VALID_SYSTEM_TOOLS because tools may be
+    // dynamically provided by an external MCP server.
+    // 3. Ensure core ADK properties exist
+    if (!config.name || (!config.yaml_reference && (!config.model || !config.instruction))) {
+        throw new Error(`[Validation Error] Configuration fails validation against ADK LlmAgentConfig specifications.`);
+    }
+}
+/**
+ * Loads a syndicate configuration from the Supabase registry.
+ * @param registryId The document ID in the adk_agent_registry table
+ * @param options Load options (bindings and overrides)
+ */
+export async function loadSyndicateFromRegistry(registryId, options = {}) {
+    if (!hasSupabaseCredentials()) {
+        throw new Error('Supabase credentials not available for registry loading.');
+    }
+    const supabaseUrl = process.env.SUPABASE_URL;
+    const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    const supabase = createClient(supabaseUrl, supabaseKey);
+    const { data, error } = await supabase
+        .from('adk_agent_registry')
+        .select('yaml_content')
+        .eq('id', registryId)
+        .single();
+    if (error || !data) {
+        throw new Error(`Registry document ${registryId} not found`);
+    }
+    const raw = data.yaml_content;
+    // Validate orchestrator
+    validateRegistryConfig(raw.orchestrator);
+    // Validate subagents
+    for (const sub of raw.subagents || []) {
+        validateRegistryConfig(sub);
+    }
+    const { bindings = {}, overrides } = options;
+    const merged = {
+        ...defaultBindings(),
+        ...(raw.variables ?? {}),
+        ...bindings,
+    };
+    const hasVars = Object.keys(merged).length > 0;
+    const interpolated = hasVars ? interpolateDeep(raw, merged) : raw;
+    if (hasVars) {
+        const unresolved = findUnresolvedTokens(interpolated);
+        if (unresolved.length > 0) {
+            console.warn(`⚠ Unresolved template variables: ${unresolved.map((t) => `{{${t}}}`).join(', ')}`);
+        }
+    }
+    const { variables: _stripped, ...clean } = interpolated;
+    let config = clean;
+    if (overrides) {
+        config = applyOverrides(config, overrides);
+    }
+    return config;
+}

package/dist/lib/memory/supabaseMemoryService.d.ts

@@ -0,0 +1,118 @@
+import type { BaseMemoryService, SearchMemoryRequest, SearchMemoryResponse, Session } from '@google/adk';
+import type { SupabaseClient } from '@supabase/supabase-js';
+/**
+ * Harness-injected blocks the Discord surface prefixes to a user message
+ * (nihilistic-penguin stocks.py): the date marker and the portfolio payload.
+ * Neither is something the USER said. Stripped from the memory SEARCH query
+ * (a portfolio JSON would dominate the embedding and drown the question) and
+ * from the extraction transcript (a snapshot that changes daily would be
+ * re-stored as "what the user holds" every session — the analyst reads the
+ * live payload directly, memory only needs what the user SAID about it).
+ */
+export declare function stripHarnessBlocks(text: string): string;
+/**
+ * Cosine similarity at or above which a new record is treated as a restatement
+ * of one already stored, and dropped.
+ *
+ * Deliberately high. The extraction model rephrases the same fact on every
+ * pass ("The user has $831 in a forgotten Roth IRA" / "…an $831 balance in a
+ * forgotten Roth IRA account"), and those land around 0.95+; genuinely
+ * different facts about one subject ("NVDA closed at $217.50" vs "Wells Fargo
+ * put a $315 target on NVDA") sit far below. Tuning this DOWN risks silently
+ * discarding a real fact, which is the worse failure — a duplicate only costs
+ * a shortlist slot.
+ */
+export declare const MEMORY_DEDUP_SIMILARITY = 0.93;
+/**
+ * Which of a session's events still need ingesting.
+ *
+ * The A2A server is stateless, so `addSessionToMemory` runs after EVERY task
+ * with the WHOLE session — an N-turn conversation was being extracted N times
+ * over a growing transcript. That produced 13 EPISODE records narrating the
+ * same session and one balance stored six ways. A high-water mark per session
+ * means each turn is distilled once.
+ */
+export declare function eventsToIngest<T>(events: T[], alreadyIngested: number): T[];
+/**
+ * True when a candidate record restates something already stored.
+ *
+ * Same tag is required: an EPISODE narrating a discussion of the user's Roth
+ * IRA is not the FACT of its balance, however close the wording sits. Retired
+ * rows never suppress a new one — a superseded record is history, and the
+ * fact it was corrected to may legitimately be re-asserted later.
+ */
+export declare function isSemanticDuplicate(candidate: {
+    tag: string;
+}, matches: Array<{
+    tag: string | null;
+    status: string | null;
+    similarity: number;
+}>, threshold?: number): boolean;
+export declare class SupabaseVectorMemoryService implements BaseMemoryService {
+    private genai;
+    private supabase;
+    /**
+     * How many of each session's events have already been distilled.
+     * Keyed `{userKey}::{sessionId}`.
+     *
+     * In-process on purpose: a restart resets it, so the next turn re-reads
+     * that session once. Semantic dedup absorbs that batch, which is why this
+     * needs no table of its own — the two fixes cover each other's edges.
+     */
+    private ingestedEventCount;
+    constructor(config: {
+        apiKey: string;
+    }, supabaseClient: SupabaseClient);
+    /**
+     * @param extractionRules Optional domain rules appended to the shared
+     *   extraction prompt for THIS consumer only. The prompt is global (the
+     *   patient advocate uses the same one), so anything domain-specific —
+     *   "never store a market quote" — arrives here rather than being edited
+     *   into it. Declared as `memory_extraction_rules` on the served syndicate.
+     */
+    addSessionToMemory(session: Session, extractionRules?: string): Promise<void>;
+    /**
+     * Right-to-erasure: permanently deletes every stored fact for a user key
+     * (`{appName}/{userId}`). Returns the number of rows removed. Throws on
+     * database error so callers can surface the failure — a silent no-op on
+     * a deletion request is unacceptable for user data.
+     *
+     * NOTE: this clears `adk_memory_facts` only. Session transcripts live in
+     * `adk_sessions` and must be cleared separately if full erasure is needed.
+     */
+    deleteUserMemory(userKey: string): Promise<number>;
+    searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    private extractRecords;
+    /**
+     * Parses one structured record line. Lines that don't match the format
+     * are dropped (extraction is best-effort; a malformed line must never
+     * poison the store). Header fields are optional individually — a bare
+     * `[FACT] text` line still parses, with defaults.
+     */
+    private parseRecord;
+    private embedTexts;
+    private serializeEvents;
+    /**
+     * Inserts new records and returns a map of record line → inserted row id
+     * (needed to link superseded rows to their replacement).
+     */
+    private upsertToSupabase;
+    /**
+     * The record evolves: a stored record carrying a `supersedes` header
+     * retires the older rows it corrects. Candidates are found by embedding
+     * the superseded quote and similarity-searching the user's ACTIVE rows;
+     * a candidate is retired when it is both semantically close and shares
+     * an index key with the correction (or is a near-exact match). Retired
+     * rows are kept — marked status='superseded' and linked via
+     * superseded_by — so history and contradictions stay inspectable.
+     */
+    private applySupersessions;
+    /**
+     * Hybrid recall: candidates come from pgvector cosine similarity, then
+     * are re-ranked by the query's connection to the record's index keys and
+     * dates. Active records outrank retired ones; retired records that still
+     * surface are relabeled so the model sees them as history, never as the
+     * current state.
+     */
+    private searchSupabase;
+}