melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/memory/supabaseMemoryService.js

@@ -1,8 +1,10 @@
-import { GoogleGenAI } from '@google/genai';
-import { EMBEDDING_MODEL, EMBEDDING_DIMENSIONS, MEMORY_EXTRACTION_MODEL } from "../config.js";
+import { memoryProvidersFromEnv, modelExtractor } from './providers.js';
+import { providerForModel } from '../models/providerMap.js';
+import { isSupabaseClient, supabaseMemoryStore } from './store.js';
 /**
- * Harness-injected blocks the Discord surface prefixes to a user message
- * (nihilistic-penguin stocks.py): the date marker and the portfolio payload.
+ * Harness-injected blocks a calling surface prefixes to a user message: the
+ * `[System Context: …]` date marker and a labelled data block (`[… Payload]`
+ * or `[… Sheet]` followed by a fenced block).
  * 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
@@ -12,7 +14,9 @@ import { EMBEDDING_MODEL, EMBEDDING_DIMENSIONS, MEMORY_EXTRACTION_MODEL } from "
 export function stripHarnessBlocks(text) {
     return text
         .replace(/\[System Context:[^\]]*\]\s*/g, '')
-        .replace(/\[(?:Portfolio Performance Payload|Stock Trade Sheet)\]\s*```[\s\S]*?```\s*/g, '')
+        // A data block a calling surface attaches: a bracketed label ending in
+        // "Payload" or "Sheet" (e.g. `[Account Payload]`), then a fenced block.
+        .replace(/\[[A-Za-z][A-Za-z ]{0,60}(?:Payload|Sheet)\]\s*```[\s\S]*?```\s*/g, '')
         .trim();
 }
 const FACT_EXTRACTION_PROMPT = `You are a precise record-keeping engine. Your job is to analyze a conversation transcript and distill it into structured, self-contained memory records that can be trusted and evolved in future conversations.
@@ -100,21 +104,47 @@ const MONTH_NAMES = [
     'july', 'august', 'september', 'october', 'november', 'december',
 ];
 export class SupabaseVectorMemoryService {
-    genai;
-    supabase;
+    extractor;
+    embedder;
+    store;
     /**
      * 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.
+     * The durable marker lives in the store when it has one
+     * (`melchizedek_memory_ingest`, migration 0007), committed with the
+     * facts; this map is the fallback for a store without it, where a restart
+     * re-reads a session once and the semantic dedup absorbs that batch.
      */
     ingestedEventCount = new Map();
-    constructor(config, supabaseClient) {
-        this.genai = new GoogleGenAI({ apiKey: config.apiKey });
-        this.supabase = supabaseClient;
-        console.log(`[MemoryService] Initialized — backend: Supabase Vector Search (pgvector), structured records`);
+    /** The server's Gemini key, for a per-syndicate Gemini extraction model. */
+    geminiKey;
+    /** Extractors for per-syndicate models (memory_extraction_model), built once. */
+    extractors = new Map();
+    buildExtractor;
+    /**
+     * @param config.apiKey The server's Gemini key, used only when the
+     *   configured extraction model or embedder is Gemini (the default).
+     * @param config.extractor / config.embedder What computes memory
+     *   (lib/memory/providers.ts, ADR 0020). Default: from the environment
+     *   (MEMORY_EXTRACTION_MODEL, MEMORY_EMBEDDING_*), which is Gemini when
+     *   nothing is set.
+     */
+    /**
+     * @param backend Where facts live: a Supabase client (REST), or any
+     *   MemoryStore, e.g. the direct-Postgres one (lib/storage/postgres).
+     */
+    constructor(config, backend) {
+        const fromEnv = config.extractor && config.embedder
+            ? undefined
+            : memoryProvidersFromEnv(process.env, config.apiKey);
+        this.extractor = config.extractor ?? fromEnv.extractor;
+        this.geminiKey = config.apiKey;
+        this.buildExtractor = config.extractorFor;
+        this.embedder = config.embedder ?? fromEnv.embedder;
+        this.store = isSupabaseClient(backend) ? supabaseMemoryStore(backend) : backend;
+        console.log(`[MemoryService] Initialized — backend: Supabase Vector Search (pgvector), structured records; `
+            + `extraction ${this.extractor.model}, embeddings ${this.embedder.provider}/${this.embedder.model} (${this.embedder.dimensions}d)`);
     }
     /**
      * @param extractionRules Optional domain rules appended to the shared
@@ -123,10 +153,20 @@ export class SupabaseVectorMemoryService {
      *   "never store a market quote" — arrives here rather than being edited
      *   into it. Declared as `memory_extraction_rules` on the served syndicate.
      */
-    async addSessionToMemory(session, extractionRules) {
+    async addSessionToMemory(session, extractionRules, options = {}) {
         const userKey = `${session.appName}/${session.userId}`;
         const watermarkKey = `${userKey}::${session.id}`;
-        const alreadyIngested = this.ingestedEventCount.get(watermarkKey) ?? 0;
+        let alreadyIngested = this.ingestedEventCount.get(watermarkKey) ?? 0;
+        // The durable marker (migration 0007), when the store has one: it
+        // survives a restart, so a turn is never distilled twice.
+        if (this.store.ingestedEvents) {
+            try {
+                alreadyIngested = Math.max(alreadyIngested, await this.store.ingestedEvents(userKey, session.id));
+            }
+            catch (err) {
+                console.error(`[MemoryService] Processed marker unreadable (using this process's):`, err instanceof Error ? err.message : err);
+            }
+        }
         const fresh = eventsToIngest(session.events ?? [], alreadyIngested);
         if (fresh.length === 0) {
             console.log(`[MemoryService] Session ${session.id}: no new turns since last ingestion — skipping.`);
@@ -139,18 +179,43 @@ export class SupabaseVectorMemoryService {
         }
         console.log(`[MemoryService] Extracting records from session: ${session.id} `
             + `(${fresh.length} new turn(s) of ${(session.events ?? []).length})`);
-        const records = await this.extractRecords(transcript, extractionRules);
-        // Advance only after extraction SUCCEEDS — a throw leaves the turns
-        // pending so the next task retries them rather than losing them.
-        this.ingestedEventCount.set(watermarkKey, (session.events ?? []).length);
+        // Every step below THROWS on failure, and the watermark advances only
+        // after the records are stored. A provider 429 during extraction, a
+        // failed embedding or a rejected insert therefore leaves these turns
+        // pending, and the next task in this session retries them. (Before,
+        // each failure was swallowed and the watermark moved past turns that
+        // were never distilled — a lost fact costs the user something they
+        // said.) A retried batch that partly landed is absorbed by the
+        // semantic dedup below.
+        const total = (session.events ?? []).length;
+        const marker = { sessionId: session.id, events: total };
+        const advance = () => this.ingestedEventCount.set(watermarkKey, total);
+        const records = await this.extractRecords(transcript, extractionRules, this.extractorFor(options.extractionModel));
         if (records.length === 0) {
+            // "No facts" is an answer: record that these turns are done.
+            if (this.store.commit)
+                await this.commitOrThrow(userKey, marker, [], []);
+            advance();
             console.log(`[MemoryService] No records extracted from session ${session.id}.`);
             return;
         }
         console.log(`[MemoryService] Extracted ${records.length} record(s) from session ${session.id}.`);
         const embeddings = await this.embedTexts(records.map(r => r.line));
+        if (this.store.commit) {
+            // One transaction: the new facts, the rows they supersede, and the
+            // marker. A failure leaves all three as they were, and the turns
+            // pending for the next task to retry (ADR 0020 item 6).
+            const payload = await this.prepareFacts(userKey, records, embeddings);
+            const kept = new Set(payload.map(p => p.fact));
+            const retire = await this.findRetirements(userKey, records.filter(r => r.supersedes && kept.has(r.line)), new Set());
+            const inserted = await this.commitOrThrow(userKey, marker, payload, retire);
+            advance();
+            console.log(`[MemoryService] Stored ${inserted.length} record(s), superseded ${retire.length}, for user key: ${userKey}`);
+            return;
+        }
         const inserted = await this.upsertToSupabase(userKey, records, embeddings);
         await this.applySupersessions(userKey, records, inserted);
+        advance();
         console.log(`[MemoryService] Stored ${inserted.size} record(s) for user key: ${userKey}`);
     }
     /**
@@ -163,15 +228,15 @@ export class SupabaseVectorMemoryService {
      * `adk_sessions` and must be cleared separately if full erasure is needed.
      */
     async deleteUserMemory(userKey) {
-        const { count, error } = await this.supabase
-            .from('adk_memory_facts')
-            .delete({ count: 'exact' })
-            .eq('user_key', userKey);
-        if (error) {
-            throw new Error(`Memory deletion failed for ${userKey}: ${error.message}`);
+        let count;
+        try {
+            count = await this.store.deleteUser(userKey);
         }
-        console.log(`[MemoryService] Deleted ${count ?? 0} fact(s) for user key: ${userKey}`);
-        return count ?? 0;
+        catch (err) {
+            throw new Error(`Memory deletion failed for ${userKey}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        console.log(`[MemoryService] Deleted ${count} fact(s) for user key: ${userKey}`);
+        return count;
     }
     async searchMemory(request) {
         const query = stripHarnessBlocks(request.query) || request.query;
@@ -179,7 +244,27 @@ export class SupabaseVectorMemoryService {
         const userKey = `${request.appName}/${request.userId}`;
         return this.searchSupabase(userKey, query);
     }
-    async extractRecords(transcript, extractionRules) {
+    /**
+     * The extractor for a syndicate's `memory_extraction_model` (ADR 0020
+     * item 4), or the deployment's. The server's Gemini key reaches only a
+     * Gemini model; another provider reads its own key from the environment.
+     */
+    extractorFor(model) {
+        if (!model || model === this.extractor.model)
+            return this.extractor;
+        let extractor = this.extractors.get(model);
+        if (!extractor) {
+            extractor = this.buildExtractor
+                ? this.buildExtractor(model)
+                : modelExtractor({
+                    model,
+                    ...(this.geminiKey && providerForModel(model) === 'gemini' ? { apiKey: this.geminiKey } : {}),
+                });
+            this.extractors.set(model, extractor);
+        }
+        return extractor;
+    }
+    async extractRecords(transcript, extractionRules, extractor = this.extractor) {
         const sessionDate = new Date().toISOString().slice(0, 10);
         // Empty by default, so a consumer that declares no rules gets exactly
         // the prompt it got before this slot existed.
@@ -191,15 +276,7 @@ export class SupabaseVectorMemoryService {
             .replace('{domain_rules}', domainRules)
             .replace('{transcript}', transcript);
         try {
-            const response = await this.genai.models.generateContent({
-                model: MEMORY_EXTRACTION_MODEL,
-                contents: [{ role: 'user', parts: [{ text: prompt }] }],
-                config: {
-                    temperature: 0.1,
-                    maxOutputTokens: 4096,
-                }
-            });
-            const text = response.text?.trim() ?? '';
+            const text = (await extractor.extract(prompt)).trim();
             if (!text || text === 'NO_FACTS_EXTRACTED')
                 return [];
             return text
@@ -209,8 +286,7 @@ export class SupabaseVectorMemoryService {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            console.error(`[MemoryService] Record extraction failed: ${msg}`);
-            return [];
+            throw new Error(`Record extraction failed (turns stay pending for retry): ${msg}`);
         }
     }
     /**
@@ -262,31 +338,13 @@ export class SupabaseVectorMemoryService {
         return { line, tag, factDate, source, status, keys, supersedes };
     }
     async embedTexts(texts) {
-        const embeddings = [];
-        for (const text of texts) {
-            try {
-                const response = await this.genai.models.embedContent({
-                    model: EMBEDDING_MODEL,
-                    contents: text,
-                    config: {
-                        outputDimensionality: EMBEDDING_DIMENSIONS
-                    }
-                });
-                if (response.embeddings && response.embeddings.length > 0) {
-                    embeddings.push(response.embeddings[0].values ?? []);
-                }
-                else {
-                    console.warn(`[MemoryService] Empty embedding returned for: "${text.slice(0, 50)}..."`);
-                    embeddings.push([]);
-                }
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                console.error(`[MemoryService] Embedding failed: ${msg}`);
-                embeddings.push([]);
-            }
+        try {
+            return await this.embedder.embed(texts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Embedding failed (turns stay pending for retry): ${msg}`);
         }
-        return embeddings;
     }
     serializeEvents(events) {
         const lines = [];
@@ -314,17 +372,41 @@ export class SupabaseVectorMemoryService {
      */
     async upsertToSupabase(userKey, records, embeddings) {
         const insertedIds = new Map();
+        const payload = await this.prepareFacts(userKey, records, embeddings);
+        if (payload.length === 0)
+            return insertedIds;
+        let data;
+        try {
+            data = await this.store.insert(payload);
+        }
+        catch (err) {
+            throw new Error(`Failed to store memory records (turns stay pending for retry): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        for (const row of data) {
+            insertedIds.set(row.fact, row.id);
+        }
+        return insertedIds;
+    }
+    /** The atomic commit, with a failure worded for the operator. */
+    async commitOrThrow(userKey, marker, rows, retire) {
+        try {
+            return await this.store.commit(userKey, marker, rows, retire);
+        }
+        catch (err) {
+            throw new Error(`Failed to store memory records (turns stay pending for retry): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * The rows worth storing: records not already stored byte for byte and
+     * not a semantic restatement of an active row of the same tag.
+     */
+    async prepareFacts(userKey, records, embeddings) {
         // First pass: byte-identical lines already stored. Cheap, and catches
         // a genuinely repeated extraction. It is NOT sufficient on its own —
         // the extraction model rephrases, so the semantic pass below is what
         // actually stops "the user has $831 in a forgotten Roth IRA" being
         // stored six ways.
-        const { data: existing } = await this.supabase
-            .from('adk_memory_facts')
-            .select('fact')
-            .eq('user_key', userKey)
-            .in('fact', records.map(r => r.line));
-        const known = new Set((existing ?? []).map((row) => row.fact));
+        const known = await this.store.existingFacts(userKey, records.map(r => r.line));
         // Second pass: semantic. One similarity probe per surviving candidate —
         // the embedding is already computed, and the same RPC the supersession
         // path uses. A restatement is dropped; the stored row keeps its
@@ -334,17 +416,16 @@ export class SupabaseVectorMemoryService {
             const record = records[i];
             if (embeddings[i].length === 0 || known.has(record.line))
                 continue;
-            const { data: near, error: nearErr } = await this.supabase.rpc('match_memory_facts', {
-                query_embedding: embeddings[i],
-                match_count: 5,
-                filter_user_key: userKey,
-            });
-            if (nearErr) {
+            let near;
+            try {
+                near = await this.store.match(userKey, embeddings[i], 5);
+            }
+            catch (err) {
                 // Fail OPEN: a dedup probe that errors must not silently drop a
                 // record. A duplicate is recoverable; a lost fact is not.
-                console.error(`[MemoryService] Dedup probe failed (storing anyway):`, nearErr.message);
+                console.error(`[MemoryService] Dedup probe failed (storing anyway):`, err instanceof Error ? err.message : err);
             }
-            else if (isSemanticDuplicate(record, (near ?? []))) {
+            if (near && isSemanticDuplicate(record, near)) {
                 console.log(`[MemoryService] Duplicate skipped [${record.tag}]: "${record.line.slice(0, 70)}..."`);
                 continue;
             }
@@ -359,20 +440,7 @@ export class SupabaseVectorMemoryService {
                 keys: record.keys,
             });
         }
-        if (payload.length === 0)
-            return insertedIds;
-        const { data, error } = await this.supabase
-            .from('adk_memory_facts')
-            .insert(payload)
-            .select('id, fact');
-        if (error) {
-            console.error(`[MemoryService] Failed to upsert to Supabase:`, error.message);
-            return insertedIds;
-        }
-        for (const row of data ?? []) {
-            insertedIds.set(row.fact, row.id);
-        }
-        return insertedIds;
+        return payload;
     }
     /**
      * The record evolves: a stored record carrying a `supersedes` header
@@ -385,47 +453,93 @@ export class SupabaseVectorMemoryService {
      */
     async applySupersessions(userKey, records, insertedIds) {
         const corrections = records.filter(r => r.supersedes && insertedIds.has(r.line));
+        const retire = await this.findRetirements(userKey, corrections, new Set(insertedIds.values()));
+        for (const r of retire) {
+            const correctionId = insertedIds.get(r.byFact);
+            try {
+                await this.store.retire(userKey, r.id, correctionId);
+                console.log(`[MemoryService] Superseded ${r.id} → ${correctionId}`);
+            }
+            catch (err) {
+                console.error(`[MemoryService] Failed to retire superseded record:`, err instanceof Error ? err.message : err);
+            }
+        }
+    }
+    /**
+     * Which active rows each correction retires: rows found by embedding the
+     * superseded quote, retired when semantically close and sharing an index
+     * key with the correction (or a near-exact match). `exclude` holds ids
+     * from this same ingestion, which are never retired.
+     */
+    async findRetirements(userKey, corrections, exclude) {
         if (corrections.length === 0)
-            return;
-        const newIds = new Set(insertedIds.values());
+            return [];
         const targetEmbeddings = await this.embedTexts(corrections.map(r => r.supersedes));
+        const out = [];
+        const taken = new Set();
         for (let i = 0; i < corrections.length; i++) {
             const correction = corrections[i];
             const vec = targetEmbeddings[i];
             if (!vec || vec.length === 0)
                 continue;
-            const { data, error } = await this.supabase.rpc('match_memory_facts', {
-                query_embedding: vec,
-                match_count: 5,
-                filter_user_key: userKey,
-            });
-            if (error) {
-                console.error(`[MemoryService] Supersession lookup failed:`, error.message);
+            let data;
+            try {
+                data = await this.store.match(userKey, vec, 5);
+            }
+            catch (err) {
+                console.error(`[MemoryService] Supersession lookup failed:`, err instanceof Error ? err.message : err);
                 continue;
             }
-            const correctionId = insertedIds.get(correction.line);
-            for (const row of (data ?? [])) {
-                if (newIds.has(row.id))
-                    continue; // never retire a record from this same ingestion
+            for (const row of data) {
+                if (exclude.has(row.id) || taken.has(row.id))
+                    continue;
                 if ((row.status ?? 'active') !== 'active')
                     continue;
                 const sharesKey = (row.keys ?? []).some(k => correction.keys.includes(k));
                 const retire = row.similarity >= 0.85 || (row.similarity >= 0.6 && sharesKey);
                 if (!retire)
                     continue;
-                const { error: updateError } = await this.supabase
-                    .from('adk_memory_facts')
-                    .update({ status: 'superseded', superseded_by: correctionId })
-                    .eq('id', row.id)
-                    .eq('user_key', userKey);
-                if (updateError) {
-                    console.error(`[MemoryService] Failed to retire superseded record:`, updateError.message);
-                }
-                else {
-                    console.log(`[MemoryService] Superseded: "${row.fact.slice(0, 60)}..." → ${correctionId}`);
-                }
+                taken.add(row.id);
+                out.push({ id: row.id, byFact: correction.line });
+                console.log(`[MemoryService] Supersedes: "${row.fact.slice(0, 60)}..."`);
             }
         }
+        return out;
+    }
+    /**
+     * Deletes facts in `namespace` older than `days` (a syndicate's
+     * memory_retention_days, ADR 0020 item 7). Returns how many; null when
+     * the store cannot prune.
+     */
+    async pruneExpired(namespace, days) {
+        if (!this.store.pruneNamespace)
+            return null;
+        const n = await this.store.pruneNamespace(namespace, days);
+        if (n)
+            console.log(`[MemoryService] Retention: deleted ${n} fact(s) older than ${days} day(s) in ${namespace}.`);
+        return n;
+    }
+    /**
+     * Refuses an embedder whose vectors would not fit the stored column
+     * (ADR 0020 item 5): every insert would fail, and the fix is a re-embed
+     * job, not dropping the table. Silent when the store cannot say.
+     */
+    async verifyEmbeddingDimensions() {
+        if (!this.store.embeddingDimensions)
+            return;
+        let stored;
+        try {
+            stored = await this.store.embeddingDimensions();
+        }
+        catch {
+            return; // migration 0007 not applied: the schema check reports that
+        }
+        if (stored != null && stored !== this.embedder.dimensions) {
+            throw new Error(`The memory table stores ${stored}-dimension embeddings, but the embedder `
+                + `${this.embedder.provider}/${this.embedder.model} produces ${this.embedder.dimensions}. `
+                + 'Set MEMORY_EMBEDDING_* to a model of that size, or re-embed the stored facts into a column of the new size; '
+                + 'never drop the table.');
+        }
     }
     /**
      * Hybrid recall: candidates come from pgvector cosine similarity, then
@@ -441,20 +555,20 @@ export class SupabaseVectorMemoryService {
             return { memories: [] };
         }
         try {
-            // Calls the Postgres RPC function `match_memory_facts` created in Supabase
-            const { data, error } = await this.supabase.rpc('match_memory_facts', {
-                query_embedding: queryVec,
-                match_count: 24,
-                filter_user_key: userKey,
-            });
-            if (error) {
-                console.error(`[MemoryService] Failed to query Supabase Vector Search:`, error.message);
+            // The `match_memory_facts` function (db/migrations/0001_base.sql),
+            // through whichever store this service was given.
+            let data;
+            try {
+                data = await this.store.match(userKey, queryVec, 24);
+            }
+            catch (err) {
+                console.error(`[MemoryService] Failed to query memory:`, err instanceof Error ? err.message : err);
                 return { memories: [] };
             }
             const q = query.toLowerCase();
             const queryYears = q.match(/\b20\d{2}\b/g) ?? [];
             const queryMonths = MONTH_NAMES.filter(mn => q.includes(mn));
-            const scored = (data ?? []).map(row => {
+            const scored = data.map(row => {
                 let score = row.similarity;
                 const status = row.status ?? 'active';
                 // Index-key channel: the query names an entity the record is filed under.

package/dist/lib/models/capabilities.d.ts

@@ -0,0 +1,103 @@
+/**
+ * lib/models/capabilities.ts — what an agent keeps and loses on the path
+ * its model will actually take.
+ *
+ * WHY this file exists:
+ *   A model id is the whole routing decision, and some of what an agent
+ *   declares only exists on one provider: Gemini grounding, xAI's x_search
+ *   and Collections, the server-side web_search sentinel that every cloud
+ *   adapter turns into its provider's native search. Until now the only
+ *   defence against losing one was a one-time console.warn inside an
+ *   adapter. This module states the loss BEFORE a request is made, per
+ *   agent, on the RESOLVED transport (direct or gateway), so the doctor
+ *   (lib/doctor.ts), the A2A startup log (lib/compile.ts) and the ledger
+ *   (llm.capability.dropped) all say the same thing.
+ *
+ * It knows nothing about gateways beyond planTransport(); a future
+ * transport that restores a native feature changes the table here, not
+ * the callers.
+ */
+import type { ProviderId } from './providerMap.ts';
+import type { TransportPlan } from './gateway.ts';
+import type { Platform } from './endpoints.ts';
+/**
+ * Server-side tool sentinels and the providers whose DIRECT adapter
+ * honours them natively. Anything not listed is a client-side function
+ * tool and travels on every path.
+ */
+export declare const SERVER_SIDE_TOOLS: Record<string, ProviderId[]>;
+export interface CapabilityReport {
+    model: string;
+    provider: ProviderId;
+    providerLabel: string;
+    transport: TransportPlan['transport'];
+    /** Gateway id when transport is 'gateway'. */
+    gateway?: string;
+    /** The cloud platform of a direct path (ADR 0023); absent on Ollama and the gateway. */
+    platform?: Platform;
+    /** False when neither a direct key nor a gateway can serve this id. */
+    funded: boolean;
+    /** The env var that would fund the direct path. */
+    keyEnv: string | null;
+    /** Declared server-side tools this path runs natively. */
+    native: string[];
+    /** Declared server-side tools this path cannot run — they are omitted. */
+    dropped: string[];
+    /** Declared client-side tools; portable across every path. */
+    portable: string[];
+}
+export declare function describeCapabilities(model: string, tools?: readonly string[], opts?: {
+    callerKey?: boolean;
+}): CapabilityReport;
+/**
+ * One line for a startup log, or undefined when there is nothing to say —
+ * a funded direct path with no dropped tool is the quiet default.
+ */
+export declare function capabilitySummary(agentName: string, r: CapabilityReport): string | undefined;
+export declare const CAPABILITIES: readonly ['delegation', 'memory_tools', 'structured_output', 'thinking_with_tools', 'streaming', 'vision', 'native_search'];
+export type Capability = (typeof CAPABILITIES)[number];
+export declare const CAPABILITY_LABELS: Record<Capability, string>;
+export type Support = 'supported' | 'degraded' | 'unsupported';
+export interface CapabilityCell {
+    support: Support;
+    /** What is lost, or what happens instead. Present unless `supported` is the whole story. */
+    note?: string;
+    evidence: 'test' | 'adk';
+}
+/** Matrix rows: each direct provider, plus the gateway transport. */
+export type MatrixRow = ProviderId | 'gateway';
+export declare const CAPABILITY_MATRIX: Record<MatrixRow, Record<Capability, CapabilityCell>>;
+/** The matrix cell for a model on the path it will actually take. */
+export declare function capabilityOf(model: string, capability: Capability, opts?: {
+    callerKey?: boolean;
+}): CapabilityCell & {
+    row: MatrixRow;
+};
+/** What one agent's YAML asks of its model. */
+export interface AgentNeedsInput {
+    tools?: readonly string[];
+    outputSchema?: unknown;
+    generateContentConfig?: {
+        thinkingConfig?: {
+            thinkingBudget?: number;
+            includeThoughts?: boolean;
+        };
+    };
+    /** True when this agent delegates to subagents through tools (DELEGATE mode). */
+    delegates?: boolean;
+}
+export declare function requiredCapabilities(agent: AgentNeedsInput): Capability[];
+export interface CapabilityGap {
+    capability: Capability;
+    support: Exclude<Support, 'supported'>;
+    row: MatrixRow;
+    note?: string;
+}
+/** The capabilities an agent needs that its resolved path does not fully give it. */
+export declare function capabilityGaps(model: string, agent: AgentNeedsInput, opts?: {
+    callerKey?: boolean;
+}): CapabilityGap[];
+/** The cell that differs from the provider's row on a platform, or undefined. */
+export declare function platformCell(provider: ProviderId, platform: Platform, capability: Capability): CapabilityCell | undefined;
+/** The matrix as a Markdown table plus notes, for documentation and the doctor. */
+export declare function renderCapabilityMatrix(): string;