@elizaos/core 2.0.0-alpha.21 → 2.0.0-alpha.22

package/dist/security/external-content.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Security utilities for handling untrusted external content.
+ *
+ * Provides functions to safely wrap and process content from
+ * external sources (emails, webhooks, web tools, etc.) before passing to LLM agents.
+ *
+ * SECURITY: External content should NEVER be directly interpolated into
+ * system prompts or treated as trusted instructions.
+ *
+ * @module security/external-content
+ */
+/**
+ * Check if content contains suspicious patterns that may indicate injection.
+ *
+ * @param content - The content to check
+ * @returns Array of matched pattern sources (empty if none)
+ */
+export declare function detectSuspiciousPatterns(content: string): string[];
+/**
+ * Source types for external content.
+ */
+export type ExternalContentSource = "email" | "webhook" | "api" | "channel_metadata" | "web_search" | "web_fetch" | "unknown";
+/**
+ * Options for wrapping external content.
+ */
+export type WrapExternalContentOptions = {
+    /** Source of the external content */
+    source: ExternalContentSource;
+    /** Original sender information (e.g., email address) */
+    sender?: string;
+    /** Subject line (for emails) */
+    subject?: string;
+    /** Whether to include detailed security warning */
+    includeWarning?: boolean;
+};
+/**
+ * Wraps external untrusted content with security boundaries and warnings.
+ *
+ * This function should be used whenever processing content from external sources
+ * (emails, webhooks, API calls from untrusted clients) before passing to LLM.
+ *
+ * @example
+ * ```ts
+ * const safeContent = wrapExternalContent(emailBody, {
+ *   source: "email",
+ *   sender: "user@example.com",
+ *   subject: "Help request"
+ * });
+ * // Pass safeContent to LLM instead of raw emailBody
+ * ```
+ *
+ * @param content - The external content to wrap
+ * @param options - Wrapping options
+ * @returns Wrapped content with security markers
+ */
+export declare function wrapExternalContent(content: string, options: WrapExternalContentOptions): string;
+/**
+ * Builds a safe prompt for handling external content.
+ * Combines the security-wrapped content with contextual information.
+ *
+ * @param params - Parameters for building the prompt
+ * @returns Safe prompt string
+ */
+export declare function buildSafeExternalPrompt(params: {
+    content: string;
+    source: ExternalContentSource;
+    sender?: string;
+    subject?: string;
+    jobName?: string;
+    jobId?: string;
+    timestamp?: string;
+}): string;
+/**
+ * Checks if a session key indicates an external hook source.
+ *
+ * @param sessionKey - The session key to check
+ * @returns True if from an external hook
+ */
+export declare function isExternalHookSession(sessionKey: string): boolean;
+/**
+ * Extracts the hook type from a session key.
+ *
+ * @param sessionKey - The session key to parse
+ * @returns The external content source type
+ */
+export declare function getHookType(sessionKey: string): ExternalContentSource;
+/**
+ * Wraps web search/fetch content with security markers.
+ * This is a simpler wrapper for web tools that just need content wrapped.
+ *
+ * @param content - The web content to wrap
+ * @param source - The source type (web_search or web_fetch)
+ * @returns Wrapped content
+ */
+export declare function wrapWebContent(content: string, source?: "web_search" | "web_fetch"): string;
+//# sourceMappingURL=external-content.d.ts.map

package/dist/security/external-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-content.d.ts","sourceRoot":"","sources":["../../src/security/external-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQlE;AAwBD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC9B,OAAO,GACP,SAAS,GACT,KAAK,GACL,kBAAkB,GAClB,YAAY,GACZ,WAAW,GACX,SAAS,CAAC;AAwFb;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACxC,qCAAqC;IACrC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,0BAA0B,GACjC,MAAM,CAyBR;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CA0BT;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAMjE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,CAWrE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,YAAY,GAAG,WAA0B,GAC/C,MAAM,CAGR"}

package/dist/security/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Security utilities for elizaOS.
+ *
+ * Provides:
+ * - Sensitive text redaction (pattern-based and secrets-based)
+ * - External content wrapping for prompt injection protection
+ *
+ * @module security
+ */
+export { buildSafeExternalPrompt, detectSuspiciousPatterns, type ExternalContentSource, getHookType, isExternalHookSession, type WrapExternalContentOptions, wrapExternalContent, wrapWebContent, } from "./external-content.js";
+export { createSecretsRedactor, getDefaultRedactPatterns, type RedactOptions, type RedactSensitiveMode, redactObjectSecrets, redactSecrets, redactSensitiveText, redactToolDetail, redactWithSecrets, type SecretsRedactOptions, } from "./redact.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACN,uBAAuB,EACvB,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,WAAW,EACX,qBAAqB,EACrB,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,cAAc,GACd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,qBAAqB,EAErB,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EAEjB,KAAK,oBAAoB,GACzB,MAAM,aAAa,CAAC"}

package/dist/security/redact.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Sensitive text redaction utilities.
+ *
+ * Provides functions to mask sensitive data like API keys, tokens,
+ * passwords, and PEM blocks in text output before logging or display.
+ *
+ * Also provides secrets-aware redaction to prevent character secrets
+ * from appearing in agent outputs or memories.
+ *
+ * @module security/redact
+ */
+/**
+ * Mode for sensitive text redaction.
+ * - "off": No redaction
+ * - "tools": Redact in tool outputs
+ */
+export type RedactSensitiveMode = "off" | "tools";
+/**
+ * Options for redacting sensitive text.
+ */
+export type RedactOptions = {
+    /** Redaction mode */
+    mode?: RedactSensitiveMode;
+    /** Custom patterns to match (in addition to or instead of defaults) */
+    patterns?: string[];
+};
+/**
+ * Options for secrets-based redaction.
+ */
+export type SecretsRedactOptions = {
+    /** Known secrets to redact (key -> secret value) */
+    secrets?: Record<string, string>;
+    /** Whether to also apply pattern-based redaction */
+    applyPatterns?: boolean;
+};
+/**
+ * Redact sensitive information from text.
+ *
+ * @param text - The text to redact
+ * @param options - Redaction options
+ * @returns Text with sensitive data masked
+ */
+export declare function redactSensitiveText(text: string, options?: RedactOptions): string;
+/**
+ * Redact sensitive information from tool output detail.
+ *
+ * Only redacts when mode is "tools" (the default).
+ *
+ * @param detail - The tool detail to redact
+ * @returns Redacted detail
+ */
+export declare function redactToolDetail(detail: string): string;
+/**
+ * Get the default redaction patterns.
+ *
+ * @returns Copy of default pattern strings
+ */
+export declare function getDefaultRedactPatterns(): string[];
+/**
+ * Redact known secrets from text.
+ *
+ * This performs literal string replacement of known secret values,
+ * ensuring they don't appear in outputs even if they don't match
+ * the pattern-based detection.
+ *
+ * @param text - Text to redact
+ * @param secrets - Map of secret names to secret values
+ * @returns Text with secrets replaced by [REDACTED:name]
+ */
+export declare function redactSecrets(text: string, secrets: Record<string, string>): string;
+/**
+ * Redact both known secrets and pattern-detected sensitive data.
+ *
+ * This combines literal secret replacement with pattern-based detection
+ * for comprehensive redaction.
+ *
+ * @param text - Text to redact
+ * @param options - Redaction options including known secrets
+ * @returns Text with all sensitive data redacted
+ */
+export declare function redactWithSecrets(text: string, options?: SecretsRedactOptions): string;
+/**
+ * Create a redaction function bound to specific secrets.
+ *
+ * This is useful for creating a redactor that can be passed around
+ * and reused without needing to pass secrets each time.
+ *
+ * @param secrets - Map of secret names to secret values
+ * @param applyPatterns - Whether to also apply pattern detection (default: true)
+ * @returns Redaction function
+ *
+ * @example
+ * ```ts
+ * const redact = createSecretsRedactor(runtime.character.settings.secrets);
+ * const safeText = redact(userMessage);
+ * ```
+ */
+export declare function createSecretsRedactor(secrets: Record<string, string>, applyPatterns?: boolean): (text: string) => string;
+/**
+ * Recursively redact secrets from an object.
+ *
+ * Walks through all string values in an object (including nested objects
+ * and arrays) and applies secret redaction.
+ *
+ * @param obj - Object to redact
+ * @param secrets - Map of secret names to secret values
+ * @param applyPatterns - Whether to also apply pattern detection
+ * @returns New object with redacted values
+ */
+export declare function redactObjectSecrets<T>(obj: T, secrets: Record<string, string>, applyPatterns?: boolean): T;
+//# sourceMappingURL=redact.d.ts.map

package/dist/security/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/security/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,OAAO,CAAC;AAwClD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC3B,qBAAqB;IACrB,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oDAAoD;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAqEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,aAAa,GACrB,MAAM,CAaR;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAEnD;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAuBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GAChC,MAAM,CAkBR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,aAAa,UAAO,GAClB,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAE1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,aAAa,UAAO,GAClB,CAAC,CAwBH"}

package/dist/security/sandbox-token-manager.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Sandbox secret token manager.
+ *
+ * Maps real secrets to opaque `stok_` prefixed tokens. Plugins see tokens;
+ * the fetch proxy resolves them to real values at the network boundary.
+ */
+export declare const SANDBOX_TOKEN_PREFIX = "stok_";
+export interface SecretTokenMetadata {
+    settingKey: string;
+    secretType: "api_key" | "oauth_token" | "password" | "private_key" | "other";
+    createdAt: number;
+    owner?: string;
+}
+export declare class SandboxTokenManager {
+    private tokenToEntry;
+    private realValueToToken;
+    private settingKeyToToken;
+    /** Register a secret, returning its stable token. Idempotent per key. */
+    registerSecret(settingKey: string, realValue: string, metadata?: Partial<SecretTokenMetadata>): string;
+    resolveToken(token: string): string | null;
+    getTokenForKey(settingKey: string): string | null;
+    getTokenForValue(realValue: string): string | null;
+    getMetadata(token: string): SecretTokenMetadata | null;
+    /** Replace tokens → real values (outbound). */
+    detokenizeString(input: string): string;
+    /** Replace real values → tokens (inbound). Longest-first to avoid partial matches. */
+    tokenizeString(input: string): string;
+    static isToken(value: string): boolean;
+    get size(): number;
+    clear(): void;
+    listKeys(): string[];
+}
+//# sourceMappingURL=sandbox-token-manager.d.ts.map

package/dist/security/sandbox-token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-token-manager.d.ts","sourceRoot":"","sources":["../../src/security/sandbox-token-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,aAAa,GAAG,OAAO,CAAC;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,iBAAiB,CAA6B;IAEtD,yEAAyE;IACzE,cAAc,CACZ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACtC,MAAM;IAgCT,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI1C,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIjD,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIlD,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAItD,+CAA+C;IAC/C,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAWvC,sFAAsF;IACtF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAcrC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAItC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,IAAI,IAAI;IAMb,QAAQ,IAAI,MAAM,EAAE;CAGrB"}

package/dist/services/action-filter.d.ts

@@ -0,0 +1,195 @@
+/**
+ * ActionFilterService — dynamically filters which actions are shown to the LLM
+ * based on relevance to the current message.
+ *
+ * Two-tier ranking:
+ *   1. Vector search: embed action descriptions + similes at registration time.
+ *      At message time, embed the query (user message + context). Use cosine
+ *      similarity to get the top candidates.
+ *   2. BM25 reranking: rerank the vector-search candidates using BM25
+ *      (term-frequency * inverse-document-frequency). BM25 is especially good
+ *      at matching specific keywords that vector search might miss.
+ *
+ * Graceful degradation:
+ *   - If the embedding model is unavailable → BM25-only ranking.
+ *   - If BM25 also fails → return all actions (same as before).
+ */
+import type { Action, IAgentRuntime, Memory, Provider } from "../types/index.ts";
+import { Service } from "../types/service.ts";
+import type { State } from "../types/state.ts";
+declare module "../types/service.ts" {
+    interface ServiceTypeRegistry {
+        ACTION_FILTER: "action_filter";
+    }
+}
+export interface RankedAction {
+    action: Action;
+    /** Cosine similarity against the query embedding (0-1 range, 0 if unavailable). */
+    vectorScore: number;
+    /** BM25 score against the query text (0+ range, 0 if unavailable). */
+    bm25Score: number;
+    /** Weighted combination of vectorScore and bm25Score, plus momentum boost. */
+    combinedScore: number;
+}
+export interface FilterConfig {
+    /** Master switch — if false the service is a no-op. */
+    enabled: boolean;
+    /** Minimum registered action count before filtering kicks in. */
+    threshold: number;
+    /** How many candidates to pull from the vector search stage. */
+    vectorTopK: number;
+    /** Final number of actions returned after reranking. */
+    finalTopK: number;
+    /** Weight for the normalized vector score in the combined score (0-1). */
+    vectorWeight: number;
+    /** Weight for the normalized BM25 score in the combined score (0-1). */
+    bm25Weight: number;
+    /** Action names that always bypass filtering (in addition to per-action alwaysInclude). */
+    alwaysIncludeActions: string[];
+    /** Time window (ms) for conversation momentum decay. */
+    momentumDecayMs: number;
+    /** Score boost for recently used actions (0-1). */
+    momentumBoost: number;
+}
+export interface FilterMetrics {
+    /** Total number of filter() invocations. */
+    filterCalls: number;
+    /** How many times filtering was actually applied (vs. passthrough). */
+    filteredCalls: number;
+    /** How many times we fell back to BM25-only (embedding unavailable). */
+    bm25OnlyFallbacks: number;
+    /** How many times we fell back to returning all actions (complete failure). */
+    fullFallbacks: number;
+    /** Reported misses — actions that were filtered out but then selected by the LLM. */
+    missCount: number;
+    /** Names of missed actions for debugging (bounded ring buffer). */
+    missedActions: string[];
+    /** Average combined-score of returned actions (last call). */
+    lastAvgScore: number;
+    /** Number of actions in the embedding index. */
+    indexedActionCount: number;
+    /** Number of actions whose embedding failed during buildIndex or addAction. */
+    embedFailureCount: number;
+}
+/**
+ * Build a rich text blob from an action's metadata, suitable for both
+ * embedding and BM25 indexing.
+ */
+export declare function getActionEmbeddingText(action: Action): string;
+/**
+ * Build a text blob from a provider's metadata for BM25 indexing.
+ * Includes name, description, and relevanceKeywords.
+ */
+export declare function getProviderIndexText(provider: Provider): string;
+/**
+ * Build the query text used for vector + BM25 matching against the action
+ * index. Includes the user message, recent conversation context, and any
+ * detected intent keywords.
+ */
+export declare function buildQueryText(message: Memory, state: State): string;
+/**
+ * Normalize an array of scores to [0, 1] using min-max normalization.
+ * Returns an array of the same length. If all values are the same,
+ * returns an array of 1s (or 0s if all are 0).
+ *
+ * NaN and Infinity values are sanitized to 0 before normalization.
+ */
+export declare function minMaxNormalize(scores: number[]): number[];
+export declare class ActionFilterService extends Service {
+    static serviceType: "action_filter";
+    capabilityDescription: string;
+    private actionEmbeddings;
+    private bm25Index;
+    /** Separate BM25 index for provider descriptions, used by filterProviders(). */
+    private providerBM25Index;
+    private filterConfig;
+    private recentActions;
+    private readonly maxRecentActions;
+    private lastFilteredByRoom;
+    private readonly maxTrackedRooms;
+    private metrics;
+    private embeddingAvailable;
+    constructor(runtime?: IAgentRuntime, config?: Partial<FilterConfig>);
+    /** Start the service. Reads ACTION_FILTER_* from runtime settings, then builds indices. */
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    stop(): Promise<void>;
+    /**
+     * Build (or rebuild) the vector + BM25 index for all registered actions.
+     * Also builds the provider BM25 index for dynamic provider filtering.
+     */
+    buildIndex(runtime: IAgentRuntime): Promise<void>;
+    /**
+     * Add a single action to the index at runtime (e.g. when a plugin
+     * registers a new action after startup).
+     */
+    addAction(action: Action, runtime: IAgentRuntime): Promise<void>;
+    /**
+     * Remove an action from both indices (e.g. when a plugin is unloaded).
+     */
+    removeAction(actionName: string): void;
+    /**
+     * Filter the registered actions to the most relevant subset for this message.
+     *
+     * Flow:
+     *  1. If action count <= threshold → return all (same as validate-all path).
+     *  2. Always-include actions bypass filtering and are prepended to results.
+     *  3. Vector search: embed query → cosine similarity → top vectorTopK.
+     *  4. BM25 rerank: score vectorTopK candidates → combine scores.
+     *  5. Apply momentum boost for recently used actions.
+     *  6. Return top finalTopK actions.
+     *
+     * The returned actions have NOT been validated — the caller (actionsProvider)
+     * is responsible for running `validate()` on the returned set.
+     */
+    filter(runtime: IAgentRuntime, message: Memory, state: State): Promise<Action[]>;
+    /**
+     * Score providers by relevance to the current message using BM25.
+     * Returns provider names sorted by relevance score, highest first.
+     * Only scores providers that have been indexed (i.e. have a description).
+     *
+     * This is used by composeState() to auto-include dynamic providers
+     * that are relevant to the current message, without requiring explicit
+     * relevanceKeywords on each provider.
+     *
+     * @param providers - The candidate providers to score (typically dynamic providers).
+     * @param message - The current message being processed.
+     * @param state - The current state (used to build query context).
+     * @param topK - Maximum number of provider names to return (default: 5).
+     * @returns Provider names sorted by descending BM25 relevance score.
+     */
+    filterProviders(providers: Provider[], message: Memory, state: State, topK?: number): string[];
+    /**
+     * Record that an action was used, so future queries in the same room
+     * receive a momentum boost for that action.
+     */
+    recordActionUse(actionName: string, roomId: string): void;
+    getMetrics(): FilterMetrics;
+    reportMiss(actionName: string): void;
+    hasAction(actionName: string): boolean;
+    getConfig(): Readonly<FilterConfig>;
+    /**
+     * Check whether an action was in the most recent filtered set for a room.
+     * Returns `true` if filtering was active for that room and the action
+     * WAS in the filtered set, `false` if it was filtered OUT, or `null` if
+     * filtering wasn't active for that room (so the caller should skip
+     * false-negative reporting).
+     */
+    wasActionInFilteredSet(actionName: string, roomId: string): boolean | null;
+    /**
+     * Override the tracked action set for a room with the exact list that was
+     * presented in the prompt. This keeps miss detection accurate when callers
+     * use filter() for ranking but still include additional actions.
+     */
+    setRoomActionSet(roomId: string, actionNames: Iterable<string>): void;
+    /**
+     * Run the full two-tier ranking pipeline on a set of candidate actions.
+     * Returns RankedAction[] sorted by combinedScore descending.
+     */
+    private rankActions;
+    /**
+     * Compute per-action momentum boosts based on recently used actions
+     * in the same room as the current message.
+     */
+    private computeMomentumBoosts;
+}
+//# sourceMappingURL=action-filter.d.ts.map

package/dist/services/action-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-filter.d.ts","sourceRoot":"","sources":["../../src/services/action-filter.ts"],"names":[],"mappings":"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"}