@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/utils/channel-utils.js

@@ -0,0 +1,337 @@
+/**
+ * Channel Utilities for elizaOS
+ *
+ * Generic cross-platform utilities for messaging channels.
+ * These utilities are platform-agnostic and can be used by any channel plugin.
+ *
+ * @module utils/channel-utils
+ */
+/**
+ * Normalize a raw chat type string to a canonical form.
+ * Handles various platform-specific naming conventions.
+ *
+ * @param raw - The raw chat type string from the platform
+ * @returns Normalized chat type
+ */
+export function normalizeChatType(raw) {
+    const lower = raw?.toLowerCase().trim();
+    if (!lower) {
+        return "direct";
+    }
+    if (lower === "direct" || lower === "dm" || lower === "private") {
+        return "direct";
+    }
+    if (lower === "group" || lower === "supergroup" || lower === "room") {
+        return "group";
+    }
+    if (lower === "channel" || lower === "feed" || lower === "broadcast") {
+        return "channel";
+    }
+    return "direct";
+}
+/**
+ * Resolve whether to process a message based on mention requirements.
+ *
+ * @param params - Mention gating parameters
+ * @returns Gating result indicating if message should be processed
+ */
+export function resolveMentionGating(params) {
+    const implicit = params.implicitMention === true;
+    const bypass = params.shouldBypassMention === true;
+    const effectiveWasMentioned = params.wasMentioned || implicit || bypass;
+    const shouldSkip = params.requireMention && params.canDetectMention && !effectiveWasMentioned;
+    return { effectiveWasMentioned, shouldSkip };
+}
+/**
+ * Resolve mention gating with command bypass logic.
+ * Allows authorized control commands to bypass mention requirements.
+ *
+ * @param params - Extended mention gating parameters
+ * @returns Extended gating result with bypass information
+ */
+export function resolveMentionGatingWithBypass(params) {
+    const shouldBypassMention = params.isGroup &&
+        params.requireMention &&
+        !params.wasMentioned &&
+        !(params.hasAnyMention ?? false) &&
+        params.allowTextCommands &&
+        params.commandAuthorized &&
+        params.hasControlCommand;
+    return {
+        ...resolveMentionGating({
+            requireMention: params.requireMention,
+            canDetectMention: params.canDetectMention,
+            wasMentioned: params.wasMentioned,
+            implicitMention: params.implicitMention,
+            shouldBypassMention,
+        }),
+        shouldBypassMention,
+    };
+}
+/**
+ * Create typing indicator callbacks with error handling.
+ *
+ * @param params - Typing callback parameters
+ * @returns Callbacks for managing typing state
+ */
+export function createTypingCallbacks(params) {
+    const stop = params.stop;
+    const onReplyStart = async () => {
+        try {
+            await params.start();
+        }
+        catch (err) {
+            params.onStartError(err);
+        }
+    };
+    const onIdle = stop
+        ? () => {
+            void stop().catch((err) => (params.onStopError ?? params.onStartError)(err));
+        }
+        : undefined;
+    return { onReplyStart, onIdle };
+}
+/**
+ * Determine if an acknowledgment reaction should be sent.
+ *
+ * @param params - Ack reaction parameters
+ * @returns Whether to send the ack reaction
+ */
+export function shouldAckReaction(params) {
+    const scope = params.scope ?? "group-mentions";
+    if (scope === "off" || scope === "none") {
+        return false;
+    }
+    if (scope === "all") {
+        return true;
+    }
+    if (scope === "direct") {
+        return params.isDirect;
+    }
+    if (scope === "group-all") {
+        return params.isGroup;
+    }
+    if (scope === "group-mentions") {
+        if (!params.isMentionableGroup) {
+            return false;
+        }
+        if (!params.requireMention) {
+            return false;
+        }
+        if (!params.canDetectMention) {
+            return false;
+        }
+        return params.effectiveWasMentioned || params.shouldBypassMention === true;
+    }
+    return false;
+}
+/**
+ * WhatsApp-specific ack reaction logic.
+ *
+ * @param params - WhatsApp ack reaction parameters
+ * @returns Whether to send the ack reaction
+ */
+export function shouldAckReactionForWhatsApp(params) {
+    if (!params.emoji) {
+        return false;
+    }
+    if (params.isDirect) {
+        return params.directEnabled;
+    }
+    if (!params.isGroup) {
+        return false;
+    }
+    if (params.groupMode === "never") {
+        return false;
+    }
+    if (params.groupMode === "always") {
+        return true;
+    }
+    return shouldAckReaction({
+        scope: "group-mentions",
+        isDirect: false,
+        isGroup: true,
+        isMentionableGroup: true,
+        requireMention: true,
+        canDetectMention: true,
+        effectiveWasMentioned: params.wasMentioned,
+        shouldBypassMention: params.groupActivated,
+    });
+}
+/**
+ * Remove acknowledgment reaction after reply is sent.
+ *
+ * @param params - Parameters for removal
+ */
+export function removeAckReactionAfterReply(params) {
+    if (!params.removeAfterReply) {
+        return;
+    }
+    if (!params.ackReactionPromise) {
+        return;
+    }
+    if (!params.ackReactionValue) {
+        return;
+    }
+    void params.ackReactionPromise.then((didAck) => {
+        if (!didAck) {
+            return;
+        }
+        params.remove().catch((err) => params.onError?.(err));
+    });
+}
+function normalizeLabel(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function getNormalizedSenderParts(params) {
+    const name = normalizeLabel(params.name);
+    const username = normalizeLabel(params.username);
+    const tag = normalizeLabel(params.tag);
+    const e164 = normalizeLabel(params.e164);
+    const id = normalizeLabel(params.id);
+    const display = name ?? username ?? tag ?? "";
+    const idPart = e164 ?? id ?? "";
+    return {
+        name,
+        username,
+        tag,
+        e164,
+        id,
+        display,
+        idPart,
+    };
+}
+/**
+ * Resolve a display label for a message sender.
+ * Prefers name, then username, then tag, with ID appended if different.
+ *
+ * @param params - Sender identification parameters
+ * @returns Display label or null if no information available
+ */
+export function resolveSenderLabel(params) {
+    const { display, idPart } = getNormalizedSenderParts(params);
+    if (display && idPart && display !== idPart) {
+        return `${display} (${idPart})`;
+    }
+    return display || idPart || null;
+}
+/**
+ * List all possible sender label candidates.
+ *
+ * @param params - Sender identification parameters
+ * @returns Array of possible labels
+ */
+export function listSenderLabelCandidates(params) {
+    const candidates = new Set();
+    const { name, username, tag, e164, id } = getNormalizedSenderParts(params);
+    if (name) {
+        candidates.add(name);
+    }
+    if (username) {
+        candidates.add(username);
+    }
+    if (tag) {
+        candidates.add(tag);
+    }
+    if (e164) {
+        candidates.add(e164);
+    }
+    if (id) {
+        candidates.add(id);
+    }
+    const resolved = resolveSenderLabel(params);
+    if (resolved) {
+        candidates.add(resolved);
+    }
+    return Array.from(candidates);
+}
+function resolveLocation(location) {
+    const source = location.source ??
+        (location.isLive
+            ? "live"
+            : location.name || location.address
+                ? "place"
+                : "pin");
+    const isLive = Boolean(location.isLive ?? source === "live");
+    return { ...location, source, isLive };
+}
+function formatAccuracy(accuracy) {
+    if (!Number.isFinite(accuracy)) {
+        return "";
+    }
+    return ` ±${Math.round(accuracy ?? 0)}m`;
+}
+function formatCoords(latitude, longitude) {
+    return `${latitude.toFixed(6)}, ${longitude.toFixed(6)}`;
+}
+/**
+ * Format a location as human-readable text with emoji indicators.
+ *
+ * @param location - Normalized location data
+ * @returns Formatted location string
+ */
+export function formatLocationText(location) {
+    const resolved = resolveLocation(location);
+    const coords = formatCoords(resolved.latitude, resolved.longitude);
+    const accuracy = formatAccuracy(resolved.accuracy);
+    const caption = resolved.caption?.trim();
+    let header = "";
+    if (resolved.source === "live" || resolved.isLive) {
+        header = `🛰 Live location: ${coords}${accuracy}`;
+    }
+    else if (resolved.name || resolved.address) {
+        const label = [resolved.name, resolved.address].filter(Boolean).join(" — ");
+        header = `📍 ${label} (${coords}${accuracy})`;
+    }
+    else {
+        header = `📍 ${coords}${accuracy}`;
+    }
+    return caption ? `${header}\n${caption}` : header;
+}
+/**
+ * Convert a normalized location to context fields.
+ *
+ * @param location - Normalized location data
+ * @returns Location context fields
+ */
+export function toLocationContext(location) {
+    const resolved = resolveLocation(location);
+    return {
+        LocationLat: resolved.latitude,
+        LocationLon: resolved.longitude,
+        LocationAccuracy: resolved.accuracy,
+        LocationName: resolved.name,
+        LocationAddress: resolved.address,
+        LocationSource: resolved.source,
+        LocationIsLive: resolved.isLive,
+    };
+}
+function formatTargetSuffix(target) {
+    return target ? ` target=${target}` : "";
+}
+/**
+ * Log when an inbound message is dropped.
+ *
+ * @param params - Log parameters
+ */
+export function logInboundDrop(params) {
+    params.log(`${params.channel}: drop ${params.reason}${formatTargetSuffix(params.target)}`);
+}
+/**
+ * Log a typing indicator failure.
+ *
+ * @param params - Log parameters
+ */
+export function logTypingFailure(params) {
+    const action = params.action ? ` action=${params.action}` : "";
+    params.log(`${params.channel} typing${action} failed${formatTargetSuffix(params.target)}: ${String(params.error)}`);
+}
+/**
+ * Log an acknowledgment cleanup failure.
+ *
+ * @param params - Log parameters
+ */
+export function logAckFailure(params) {
+    params.log(`${params.channel} ack cleanup failed${formatTargetSuffix(params.target)}: ${String(params.error)}`);
+}

package/packages/typescript/src/utils/context-catalog.d.ts

@@ -0,0 +1,6 @@
+import type { Action, AgentContext, Provider } from "../types/components";
+export declare const ACTION_CONTEXT_MAP: Record<string, AgentContext[]>;
+export declare const PROVIDER_CONTEXT_MAP: Record<string, AgentContext[]>;
+export declare function resolveActionContexts(action: Action): AgentContext[];
+export declare function resolveProviderContexts(provider: Provider): AgentContext[];
+//# sourceMappingURL=context-catalog.d.ts.map

package/packages/typescript/src/utils/context-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-catalog.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/context-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE1E,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAqG7D,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAsB/D,CAAC;AAUF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAOpE;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,EAAE,CAO1E"}

package/packages/typescript/src/utils/context-catalog.js

@@ -0,0 +1,144 @@
+export const ACTION_CONTEXT_MAP = {
+    NONE: ["general"],
+    IGNORE: ["general"],
+    CONTINUE: ["general"],
+    REPLY: ["general"],
+    HELP: ["general"],
+    STATUS: ["general"],
+    MODELS: ["general"],
+    CONFIGURE: ["general", "system"],
+    LAUNCH_APP: ["apps"],
+    STOP_APP: ["apps"],
+    LIST_RUNNING_APPS: ["apps"],
+    MODIFY_CHARACTER: ["character", "system"],
+    SEND_TOKEN: ["wallet"],
+    TRANSFER: ["wallet"],
+    CHECK_BALANCE: ["wallet"],
+    GET_BALANCE: ["wallet"],
+    SWAP_TOKEN: ["wallet", "automation"],
+    BRIDGE_TOKEN: ["wallet"],
+    APPROVE_TOKEN: ["wallet"],
+    SIGN_MESSAGE: ["wallet"],
+    DEPLOY_CONTRACT: ["wallet", "code"],
+    CREATE_GOVERNANCE_PROPOSAL: ["wallet", "social"],
+    VOTE_ON_PROPOSAL: ["wallet", "social"],
+    STAKE: ["wallet"],
+    UNSTAKE: ["wallet"],
+    CLAIM_REWARDS: ["wallet"],
+    GET_TOKEN_PRICE: ["wallet", "knowledge"],
+    GET_PORTFOLIO: ["wallet"],
+    CREATE_WALLET: ["wallet"],
+    IMPORT_WALLET: ["wallet"],
+    SEARCH_KNOWLEDGE: ["knowledge"],
+    ADD_KNOWLEDGE: ["knowledge"],
+    REMEMBER: ["knowledge"],
+    RECALL: ["knowledge"],
+    LEARN_FROM_EXPERIENCE: ["knowledge"],
+    SEARCH_WEB: ["knowledge", "browser"],
+    WEB_SEARCH: ["knowledge", "browser"],
+    SUMMARIZE: ["knowledge"],
+    ANALYZE: ["knowledge"],
+    BROWSER_SESSION: ["browser"],
+    BROWSE: ["browser"],
+    SCREENSHOT: ["browser", "media"],
+    NAVIGATE: ["browser"],
+    CLICK: ["browser"],
+    TYPE_TEXT: ["browser"],
+    EXTRACT_PAGE: ["browser", "knowledge"],
+    SPAWN_AGENT: ["code", "automation"],
+    KILL_AGENT: ["code", "automation"],
+    UPDATE_AGENT: ["code", "system"],
+    RUN_SCRIPT: ["code", "automation"],
+    REVIEW_CODE: ["code"],
+    GENERATE_CODE: ["code"],
+    EXECUTE_TASK: ["code", "automation"],
+    CREATE_SUBTASK: ["code", "automation"],
+    COMPLETE_TASK: ["code", "automation"],
+    CANCEL_TASK: ["code", "automation"],
+    GENERATE_IMAGE: ["media"],
+    DESCRIBE_IMAGE: ["media", "knowledge"],
+    DESCRIBE_VIDEO: ["media", "knowledge"],
+    DESCRIBE_AUDIO: ["media", "knowledge"],
+    TEXT_TO_SPEECH: ["media"],
+    TRANSCRIBE: ["media", "knowledge"],
+    UPLOAD_FILE: ["media"],
+    CREATE_CRON: ["automation"],
+    UPDATE_CRON: ["automation"],
+    DELETE_CRON: ["automation"],
+    LIST_CRONS: ["automation"],
+    PAUSE_CRON: ["automation"],
+    RUN_CRON: ["automation"],
+    CREATE_N8N_WORKFLOW: ["automation"],
+    ACTIVATE_N8N_WORKFLOW: ["automation"],
+    DEACTIVATE_N8N_WORKFLOW: ["automation"],
+    DELETE_N8N_WORKFLOW: ["automation"],
+    GET_N8N_EXECUTIONS: ["automation"],
+    TRIGGER_WEBHOOK: ["automation"],
+    SCHEDULE: ["automation"],
+    SEND_MESSAGE: ["social"],
+    OWNER_SEND_MESSAGE: ["social"],
+    OWNER_INBOX: ["social", "knowledge"],
+    OWNER_RELATIONSHIP: ["social"],
+    OWNER_CALENDAR: ["automation", "social"],
+    RUN_MORNING_CHECKIN: ["automation"],
+    RUN_NIGHT_CHECKIN: ["automation"],
+    UPDATE_OWNER_PROFILE: ["social"],
+    ADD_CONTACT: ["social"],
+    UPDATE_CONTACT: ["social"],
+    GET_CONTACT: ["social"],
+    SEARCH_CONTACTS: ["social"],
+    ELEVATE_TRUST: ["social", "system"],
+    REVOKE_TRUST: ["social", "system"],
+    BLOCK_USER: ["social", "system"],
+    UNBLOCK_USER: ["social", "system"],
+    MANAGE_PLUGINS: ["system"],
+    MANAGE_SECRETS: ["system"],
+    SHELL_EXEC: ["system", "code"],
+    RESTART: ["system"],
+    CONFIGURE_RUNTIME: ["system"],
+    OAUTH_CONNECT: ["system", "social"],
+    SEARCH_ACTIONS: ["system", "knowledge"],
+    FINISH: ["general"],
+};
+export const PROVIDER_CONTEXT_MAP = {
+    time: ["general"],
+    boredom: ["general"],
+    facts: ["general", "knowledge"],
+    knowledge: ["knowledge"],
+    entities: ["social"],
+    relationships: ["social"],
+    recentMessages: ["general"],
+    worldInfo: ["general"],
+    roleInfo: ["general"],
+    settings: ["system"],
+    walletBalance: ["wallet"],
+    walletPortfolio: ["wallet"],
+    tokenPrices: ["wallet", "knowledge"],
+    chainInfo: ["wallet"],
+    contacts: ["social"],
+    trustScores: ["social"],
+    platformIdentity: ["social"],
+    cronJobs: ["automation"],
+    taskList: ["automation", "code"],
+    agentConfig: ["system"],
+    pluginList: ["system"],
+};
+function normalizeContexts(contexts) {
+    return Array.isArray(contexts)
+        ? contexts.filter((context) => Boolean(context))
+        : [];
+}
+export function resolveActionContexts(action) {
+    const declared = normalizeContexts(action.contexts);
+    if (declared.length > 0) {
+        return declared;
+    }
+    return ACTION_CONTEXT_MAP[action.name.toUpperCase()] ?? ["general"];
+}
+export function resolveProviderContexts(provider) {
+    const declared = normalizeContexts(provider.contexts);
+    if (declared.length > 0) {
+        return declared;
+    }
+    return PROVIDER_CONTEXT_MAP[provider.name] ?? ["general"];
+}

package/packages/typescript/src/utils/context-routing.d.ts

@@ -0,0 +1,25 @@
+import type { Action, AgentContext, Provider } from "../types/components";
+import type { Memory } from "../types/memory";
+import type { State } from "../types/state";
+export declare const AVAILABLE_CONTEXTS_STATE_KEY = "availableContexts";
+export declare const CONTEXT_ROUTING_METADATA_KEY = "__responseContext";
+export declare const CONTEXT_ROUTING_STATE_KEY = "__contextRouting";
+export interface ContextRoutingDecision {
+    primaryContext?: AgentContext;
+    secondaryContexts?: AgentContext[];
+    evidenceTurnIds?: string[];
+}
+export declare function parseContextList(value: unknown): AgentContext[];
+export declare function parseContextRoutingMetadata(raw: unknown): ContextRoutingDecision;
+export declare function getContextRoutingFromState(state: State | null | undefined): ContextRoutingDecision;
+export declare function getContextRoutingFromMessage(message: Memory): ContextRoutingDecision;
+export declare function mergeContextRouting(state: State | null | undefined, message: Memory): ContextRoutingDecision;
+export declare function getActiveRoutingContexts(routing: ContextRoutingDecision): AgentContext[];
+export declare function shouldIncludeByContext(declaredContexts: AgentContext[] | undefined, activeContexts: AgentContext[] | undefined): boolean;
+export declare function setContextRoutingMetadata(message: Memory, routing: ContextRoutingDecision): void;
+export declare function deriveAvailableContexts(actions: Action[], providers: Provider[]): AgentContext[];
+export declare function attachAvailableContexts(state: State, runtime: {
+    actions: Action[];
+    providers: Provider[];
+}): State;
+//# sourceMappingURL=context-routing.d.ts.map

package/packages/typescript/src/utils/context-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-routing.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/context-routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAM5C,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAChE,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAChE,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAI5D,MAAM,WAAW,sBAAsB;IACtC,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,iBAAiB,CAAC,EAAE,YAAY,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AA2CD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CAI/D;AAED,wBAAgB,2BAA2B,CAC1C,GAAG,EAAE,OAAO,GACV,sBAAsB,CAiBxB;AAED,wBAAgB,0BAA0B,CACzC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAC7B,sBAAsB,CAGxB;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,MAAM,GACb,sBAAsB,CAQxB;AAED,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,EAC/B,OAAO,EAAE,MAAM,GACb,sBAAsB,CAyBxB;AAED,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,sBAAsB,GAC7B,YAAY,EAAE,CAehB;AAED,wBAAgB,sBAAsB,CACrC,gBAAgB,EAAE,YAAY,EAAE,GAAG,SAAS,EAC5C,cAAc,EAAE,YAAY,EAAE,GAAG,SAAS,GACxC,OAAO,CAcT;AAED,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,sBAAsB,GAC7B,IAAI,CAiBN;AAED,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,QAAQ,EAAE,GACnB,YAAY,EAAE,CAmBhB;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,GACnD,KAAK,CAYP"}

package/packages/typescript/src/utils/context-routing.js

@@ -0,0 +1,164 @@
+import { resolveActionContexts, resolveProviderContexts, } from "./context-catalog";
+export const AVAILABLE_CONTEXTS_STATE_KEY = "availableContexts";
+export const CONTEXT_ROUTING_METADATA_KEY = "__responseContext";
+export const CONTEXT_ROUTING_STATE_KEY = "__contextRouting";
+const LIST_SPLIT_RE = /[\n,;]/;
+function normalizeContext(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim().toLowerCase();
+    return trimmed ? trimmed : undefined;
+}
+function dedupeStringValues(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const lower = trimmed.toLowerCase();
+        if (seen.has(lower)) {
+            continue;
+        }
+        seen.add(lower);
+        result.push(trimmed);
+    }
+    return result;
+}
+function parseDelimitedList(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value)) {
+        return dedupeStringValues(value.flatMap((entry) => typeof entry === "string"
+            ? entry.split(LIST_SPLIT_RE)
+            : [String(entry)]));
+    }
+    if (typeof value === "string") {
+        return dedupeStringValues(value.split(LIST_SPLIT_RE));
+    }
+    return [];
+}
+export function parseContextList(value) {
+    return dedupeStringValues(parseDelimitedList(value))
+        .map((context) => normalizeContext(context))
+        .filter((context) => Boolean(context));
+}
+export function parseContextRoutingMetadata(raw) {
+    if (!raw || typeof raw !== "object") {
+        return {};
+    }
+    const value = raw;
+    const primaryContext = normalizeContext(value.primaryContext);
+    const secondaryContexts = parseContextList(value.secondaryContexts);
+    const evidenceTurnIds = dedupeStringValues(parseDelimitedList(value.evidenceTurnIds));
+    return {
+        primaryContext,
+        secondaryContexts,
+        evidenceTurnIds,
+    };
+}
+export function getContextRoutingFromState(state) {
+    if (!state?.values)
+        return {};
+    return parseContextRoutingMetadata(state.values[CONTEXT_ROUTING_STATE_KEY]);
+}
+export function getContextRoutingFromMessage(message) {
+    const metadata = message.content?.metadata;
+    if (!metadata || typeof metadata !== "object") {
+        return {};
+    }
+    return parseContextRoutingMetadata(metadata[CONTEXT_ROUTING_METADATA_KEY]);
+}
+export function mergeContextRouting(state, message) {
+    const stateRouting = getContextRoutingFromState(state);
+    const messageRouting = getContextRoutingFromMessage(message);
+    const mergedSecondary = dedupeStringValues([
+        ...(stateRouting.secondaryContexts || []),
+        ...(messageRouting.secondaryContexts || []),
+    ]);
+    const mergedEvidenceTurnIds = dedupeStringValues([
+        ...(stateRouting.evidenceTurnIds || []),
+        ...(messageRouting.evidenceTurnIds || []),
+    ]);
+    const primaryContext = messageRouting.primaryContext || stateRouting.primaryContext || undefined;
+    if (primaryContext && !mergedSecondary.includes(primaryContext)) {
+        mergedSecondary.unshift(primaryContext);
+    }
+    return {
+        primaryContext,
+        secondaryContexts: mergedSecondary,
+        evidenceTurnIds: mergedEvidenceTurnIds,
+    };
+}
+export function getActiveRoutingContexts(routing) {
+    const contextSet = new Set();
+    if (routing.primaryContext) {
+        contextSet.add(routing.primaryContext);
+    }
+    for (const context of routing.secondaryContexts || []) {
+        if (context) {
+            contextSet.add(context);
+        }
+    }
+    if (contextSet.size === 0) {
+        return [];
+    }
+    contextSet.add("general");
+    return Array.from(contextSet);
+}
+export function shouldIncludeByContext(declaredContexts, activeContexts) {
+    if (!declaredContexts || declaredContexts.length === 0) {
+        return true;
+    }
+    if (!activeContexts || activeContexts.length === 0) {
+        return true;
+    }
+    const normalizedActive = new Set((activeContexts || []).map((context) => `${context}`.toLowerCase()));
+    return declaredContexts.some((context) => normalizedActive.has(`${context}`.toLowerCase()));
+}
+export function setContextRoutingMetadata(message, routing) {
+    const existingMetadata = message.content && typeof message.content.metadata === "object"
+        ? message.content.metadata
+        : {};
+    if (!message.content || typeof message.content !== "object") {
+        return;
+    }
+    message.content = {
+        ...message.content,
+        metadata: {
+            ...existingMetadata,
+            [CONTEXT_ROUTING_METADATA_KEY]: routing,
+        },
+    };
+}
+export function deriveAvailableContexts(actions, providers) {
+    const contextSet = new Set(["general"]);
+    for (const action of actions) {
+        for (const context of resolveActionContexts(action)) {
+            const normalized = normalizeContext(context);
+            if (normalized) {
+                contextSet.add(normalized);
+            }
+        }
+    }
+    for (const provider of providers) {
+        for (const context of resolveProviderContexts(provider)) {
+            const normalized = normalizeContext(context);
+            if (normalized) {
+                contextSet.add(normalized);
+            }
+        }
+    }
+    return Array.from(contextSet).sort((a, b) => `${a}`.localeCompare(`${b}`));
+}
+export function attachAvailableContexts(state, runtime) {
+    const availableContexts = deriveAvailableContexts(runtime.actions, runtime.providers);
+    return {
+        ...state,
+        values: {
+            ...(state.values || {}),
+            [AVAILABLE_CONTEXTS_STATE_KEY]: availableContexts.join(", "),
+        },
+    };
+}