@elizaos/agent 2.0.0-beta.2 → 2.0.3-beta.3

package/services/plugin-manager-types.d.ts

@@ -0,0 +1,114 @@
+import type { AppUiExtensionConfig, RegistryAppMeta, RegistryAppSessionFeature, RegistryAppSessionMeta, RegistryAppSessionMode, RegistryAppViewerMeta, RegistryPluginInfo as RegistryClientPluginInfo, RegistrySearchResult as RegistryClientSearchResult } from "./registry-client-types.js";
+export type { AppUiExtensionConfig };
+export type RegistryVersionSupport = RegistryClientPluginInfo["supports"];
+export type RegistryPluginNpmInfo = RegistryClientPluginInfo["npm"];
+export type RegistryPluginViewerInfo = RegistryAppViewerMeta;
+export type RegistryPluginAppSessionMode = RegistryAppSessionMode;
+export type RegistryPluginAppSessionFeature = RegistryAppSessionFeature;
+export type RegistryPluginAppSessionInfo = RegistryAppSessionMeta;
+export type RegistryPluginAppMeta = RegistryAppMeta;
+export interface RegistryPluginInfo extends RegistryClientPluginInfo {
+    displayName?: string;
+    launchType?: string;
+    launchUrl?: string | null;
+    viewer?: RegistryPluginViewerInfo;
+    uiExtension?: AppUiExtensionConfig;
+    category?: string;
+    capabilities?: string[];
+    icon?: string | null;
+    heroImage?: string | null;
+    runtimePlugin?: string;
+    session?: RegistryPluginAppSessionInfo;
+}
+export interface RegistrySearchResult extends RegistryClientSearchResult {
+    version?: string | null;
+    npmPackage?: string;
+}
+export interface InstalledPluginInfo {
+    name: string;
+    version?: string;
+    installedAt?: string;
+    releaseStream?: "latest" | "beta";
+    requestedVersion?: string;
+    latestVersion?: string | null;
+    betaVersion?: string | null;
+}
+export interface PluginInstallOptionsLike {
+    version?: string;
+    releaseStream?: "latest" | "beta";
+}
+export interface InstallProgressLike {
+    phase: string;
+    message: string;
+    pluginName?: string;
+}
+export interface PluginInstallResult {
+    success: boolean;
+    pluginName: string;
+    version: string;
+    installPath: string;
+    requiresRestart: boolean;
+    requestedVersion?: string;
+    releaseStream?: "latest" | "beta";
+    latestVersion?: string | null;
+    betaVersion?: string | null;
+    error?: string;
+}
+export interface PluginUninstallResult {
+    success: boolean;
+    pluginName: string;
+    requiresRestart: boolean;
+    error?: string;
+}
+export interface EjectResult {
+    success: boolean;
+    pluginName: string;
+    ejectedPath: string;
+    requiresRestart: boolean;
+    error?: string;
+}
+export interface SyncResult {
+    success: boolean;
+    pluginName: string;
+    ejectedPath: string;
+    requiresRestart: boolean;
+    error?: string;
+}
+export interface ReinjectResult {
+    success: boolean;
+    pluginName: string;
+    removedPath: string;
+    requiresRestart: boolean;
+    error?: string;
+}
+export interface PluginManagerLike {
+    refreshRegistry(): Promise<Map<string, RegistryPluginInfo>>;
+    listInstalledPlugins(): Promise<InstalledPluginInfo[]>;
+    getRegistryPlugin(name: string): Promise<RegistryPluginInfo | null>;
+    searchRegistry(query: string, limit?: number): Promise<RegistrySearchResult[]>;
+    installPlugin(pluginName: string, onProgress?: (progress: InstallProgressLike) => void, options?: PluginInstallOptionsLike): Promise<PluginInstallResult>;
+    updatePlugin?(pluginName: string, onProgress?: (progress: InstallProgressLike) => void, options?: PluginInstallOptionsLike): Promise<PluginInstallResult>;
+    uninstallPlugin(pluginName: string): Promise<PluginUninstallResult>;
+    listEjectedPlugins(): Promise<InstalledPluginInfo[]>;
+    ejectPlugin(pluginName: string): Promise<EjectResult>;
+    syncPlugin(pluginName: string): Promise<SyncResult>;
+    reinjectPlugin(pluginName: string): Promise<ReinjectResult>;
+}
+export interface CoreStatusLike {
+    ejected: boolean;
+    ejectedPath: string;
+    monorepoPath: string;
+    corePackagePath: string;
+    coreDistPath: string;
+    version: string;
+    npmVersion: string;
+    commitHash: string | null;
+    localChanges: boolean;
+    upstream: unknown;
+}
+export interface CoreManagerLike {
+    getCoreStatus(): Promise<CoreStatusLike>;
+}
+export declare function isPluginManagerLike(candidate: unknown): candidate is PluginManagerLike;
+export declare function isCoreManagerLike(candidate: unknown): candidate is CoreManagerLike;
+//# sourceMappingURL=plugin-manager-types.d.ts.map

package/services/plugin-manager-types.d.ts.map

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

package/services/proactive-interaction-decider.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Proactive-interaction decider (#8792).
+ *
+ * Consumes UI interaction events (view switches, slash commands, shortcuts) and
+ * decides whether to surface a single scoped, helpful offer through either the
+ * existing `routeAutonomyTextToUser` → `proactive-message` pipeline with
+ * `source: "proactive-interaction"` or the low-priority notification rail.
+ *
+ * Two layers, both testable in isolation:
+ *  - {@link decideProactiveComment} — the pure policy + governance decision
+ *    (injected judge / gate / clock), no runtime, no model, no network.
+ *  - {@link registerProactiveInteractionDecider} — the thin runtime wiring that
+ *    subscribes to the event bus, runs the small-model judge, and routes the
+ *    admitted comment.
+ */
+import { type IAgentRuntime, type ShortcutFiredPayload, type SlashCommandInvokedPayload, type ViewSwitchedPayload } from "@elizaos/core";
+import { type ProactiveInteractionGate } from "./proactive-interaction-gate.js";
+/** Source tag for proactive comments driven by UI interactions. */
+export declare const PROACTIVE_INTERACTION_SOURCE = "proactive-interaction";
+/** Any interaction the decider reacts to (#8792). */
+export type InteractionPayload = ViewSwitchedPayload | SlashCommandInvokedPayload | ShortcutFiredPayload;
+/**
+ * Runtime setting key for the user-facing "Proactive suggestions" control
+ * (off/subtle/chatty). Read via `runtime.getSetting`, it takes precedence over
+ * the `ELIZA_PROACTIVE_INTERACTIONS` env default inside the gate resolver.
+ */
+export declare const PROACTIVE_CHATTINESS_SETTING_KEY = "ELIZA_PROACTIVE_INTERACTIONS";
+/** Where an admitted proactive offer should be delivered. */
+export type ProactiveDelivery = "chat" | "notify";
+/** A scoped offer from the judge, normalized before governance/admission. */
+export interface ProactiveOffer {
+    text: string;
+    delivery: ProactiveDelivery;
+    title?: string;
+    deepLink?: string;
+    groupKey?: string;
+}
+/** A model judge: given an interaction context, return an offer or null. */
+export type ProactiveJudgeResult = string | ProactiveOffer | null;
+export type ProactiveJudge = (payload: InteractionPayload) => Promise<ProactiveJudgeResult>;
+export interface DecideProactiveInput {
+    payload: InteractionPayload;
+    gate: ProactiveInteractionGate;
+    judge: ProactiveJudge;
+    now: number;
+}
+/**
+ * Control / dismiss / help shortcuts that must never trigger a proactive comment
+ * (#8792). These are gestures, not intent: commenting on them is noise, and —
+ * critically — the small-model judge runs BEFORE the governance gate, so letting
+ * them reach the judge would spend a TEXT_SMALL call per keystroke. Denying them
+ * here (a surface of `null`) skips the judge entirely. Navigation-bearing
+ * shortcuts ("open X") report `VIEW_SWITCHED` through the navigate route instead,
+ * so SHORTCUT_FIRED stays a small, high-signal channel for non-navigation
+ * capability-invokes (e.g. opening the command palette).
+ */
+export declare const NON_PROACTIVE_SHORTCUT_IDS: ReadonlySet<string>;
+/**
+ * The governance surface for an interaction, or `null` when policy says never
+ * comment. Explicitly-typed slash commands return `null`: the user already
+ * expressed intent and the command produced its own reply, so a proactive
+ * comment would be double-talk (#8792 open question). Control/dismiss shortcuts
+ * are denied (see {@link NON_PROACTIVE_SHORTCUT_IDS}). View switches key on the
+ * view; remaining (intent-bearing) shortcuts key on the shortcut id.
+ */
+export declare function interactionSurface(payload: InteractionPayload): string | null;
+export interface DecideProactiveResult {
+    /** The comment to surface, or null when none should be sent. */
+    text: string | null;
+    /** Delivery rail for the admitted text. Null when no text is admitted. */
+    delivery: ProactiveDelivery | null;
+    /** Optional notification headline when delivery is notify. */
+    title?: string;
+    deepLink?: string;
+    groupKey?: string;
+    reason: string;
+}
+/**
+ * Decide whether to comment on a view switch. Policy + governance only:
+ *  - Skip AGENT-initiated switches — the agent already acknowledged the move
+ *    (#8788), so a second proactive comment would be double-talk.
+ *  - Require the caller-recorded switch to have settled, then ask the judge for
+ *    a scoped offer.
+ *  - A null/empty judge result means "nothing helpful to say" → silence.
+ *  - The governance gate (cooldowns / cap / dedup / debounce) makes the final
+ *    call and records the emission.
+ */
+export declare function decideProactiveComment(input: DecideProactiveInput): Promise<DecideProactiveResult>;
+/** Build the small-model judge prompt for an interaction. */
+export declare function buildProactiveJudgePrompt(payload: InteractionPayload): string;
+/** Parse the judge model output into a typed offer or null. */
+export declare function parseProactiveJudgeDecisionOutput(raw: unknown): ProactiveOffer | null;
+/** Parse the judge model output into an offer string or null. */
+export declare function parseProactiveJudgeOutput(raw: unknown): string | null;
+export interface ProactiveDeciderWiring {
+    /** Route an admitted comment to the user (proactive-message pipeline). */
+    route: (text: string) => Promise<void>;
+    /** Route an admitted low-urgency offer to the notification rail. */
+    notify?: (offer: ProactiveOffer) => Promise<void>;
+    /** Suppress comments while a foreground chat turn is already speaking/typing. */
+    shouldSuppress?: () => boolean;
+    gate: ProactiveInteractionGate;
+    /** Override the clock (tests). */
+    now?: () => number;
+}
+/**
+ * Subscribe the decider to the runtime event bus. Each VIEW_SWITCHED runs the
+ * small-model judge and, if the governance gate admits, routes the comment.
+ * Fire-and-forget; failures degrade silently (a missed proactive comment must
+ * never break the interaction).
+ */
+export declare function registerProactiveInteractionDecider(runtime: IAgentRuntime, wiring: ProactiveDeciderWiring): void;
+//# sourceMappingURL=proactive-interaction-decider.d.ts.map

package/services/proactive-interaction-decider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proactive-interaction-decider.d.ts","sourceRoot":"","sources":["../../src/services/proactive-interaction-decider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAEL,KAAK,aAAa,EAGlB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,iCAAiC,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAC1B,mBAAmB,GACnB,0BAA0B,GAC1B,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,iCAAiC,CAAC;AAE/E,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElD,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,kBAAkB,KACxB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,cAAc,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAQzD,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAgDhC;AAsBD,6DAA6D;AAC7D,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAE7E;AA4BD,+DAA+D;AAC/D,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,OAAO,GACX,cAAc,GAAG,IAAI,CAgCvB;AAED,iEAAiE;AACjE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAErE;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;IAC/B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAyGN"}

package/services/proactive-interaction-decider.js

@@ -0,0 +1,333 @@
+/**
+ * Proactive-interaction decider (#8792).
+ *
+ * Consumes UI interaction events (view switches, slash commands, shortcuts) and
+ * decides whether to surface a single scoped, helpful offer through either the
+ * existing `routeAutonomyTextToUser` → `proactive-message` pipeline with
+ * `source: "proactive-interaction"` or the low-priority notification rail.
+ *
+ * Two layers, both testable in isolation:
+ *  - {@link decideProactiveComment} — the pure policy + governance decision
+ *    (injected judge / gate / clock), no runtime, no model, no network.
+ *  - {@link registerProactiveInteractionDecider} — the thin runtime wiring that
+ *    subscribes to the event bus, runs the small-model judge, and routes the
+ *    admitted comment.
+ */
+import { EventType, logger, ModelType, } from "@elizaos/core";
+import { resolveProactiveGateConfig, } from "./proactive-interaction-gate.js";
+/** Source tag for proactive comments driven by UI interactions. */
+export const PROACTIVE_INTERACTION_SOURCE = "proactive-interaction";
+/**
+ * Runtime setting key for the user-facing "Proactive suggestions" control
+ * (off/subtle/chatty). Read via `runtime.getSetting`, it takes precedence over
+ * the `ELIZA_PROACTIVE_INTERACTIONS` env default inside the gate resolver.
+ */
+export const PROACTIVE_CHATTINESS_SETTING_KEY = "ELIZA_PROACTIVE_INTERACTIONS";
+/**
+ * Control / dismiss / help shortcuts that must never trigger a proactive comment
+ * (#8792). These are gestures, not intent: commenting on them is noise, and —
+ * critically — the small-model judge runs BEFORE the governance gate, so letting
+ * them reach the judge would spend a TEXT_SMALL call per keystroke. Denying them
+ * here (a surface of `null`) skips the judge entirely. Navigation-bearing
+ * shortcuts ("open X") report `VIEW_SWITCHED` through the navigate route instead,
+ * so SHORTCUT_FIRED stays a small, high-signal channel for non-navigation
+ * capability-invokes (e.g. opening the command palette).
+ */
+export const NON_PROACTIVE_SHORTCUT_IDS = new Set([
+    "close-modal",
+    "send-message",
+    "focus-composer",
+    "pause-resume-agent",
+    "restart-agent",
+    "toggle-terminal",
+    "show-keyboard-shortcuts",
+]);
+/**
+ * The governance surface for an interaction, or `null` when policy says never
+ * comment. Explicitly-typed slash commands return `null`: the user already
+ * expressed intent and the command produced its own reply, so a proactive
+ * comment would be double-talk (#8792 open question). Control/dismiss shortcuts
+ * are denied (see {@link NON_PROACTIVE_SHORTCUT_IDS}). View switches key on the
+ * view; remaining (intent-bearing) shortcuts key on the shortcut id.
+ */
+export function interactionSurface(payload) {
+    if ("command" in payload)
+        return null; // explicit slash — stay silent
+    if ("shortcutId" in payload) {
+        if (NON_PROACTIVE_SHORTCUT_IDS.has(payload.shortcutId))
+            return null;
+        return `shortcut:${payload.shortcutId}`;
+    }
+    if ("viewId" in payload && payload.viewId)
+        return payload.viewId;
+    return null;
+}
+function normalizeProactiveOffer(result) {
+    if (typeof result === "string") {
+        const text = result.trim();
+        if (!text || text.toLowerCase() === "none" || text === "null")
+            return null;
+        return { text, delivery: "chat" };
+    }
+    if (!result || typeof result !== "object")
+        return null;
+    const text = result.text.trim();
+    if (!text || text.toLowerCase() === "none" || text === "null")
+        return null;
+    return {
+        text,
+        delivery: result.delivery === "notify" ? "notify" : "chat",
+        title: result.title?.trim() || undefined,
+        deepLink: result.deepLink?.trim() || undefined,
+        groupKey: result.groupKey?.trim() || undefined,
+    };
+}
+/**
+ * Decide whether to comment on a view switch. Policy + governance only:
+ *  - Skip AGENT-initiated switches — the agent already acknowledged the move
+ *    (#8788), so a second proactive comment would be double-talk.
+ *  - Require the caller-recorded switch to have settled, then ask the judge for
+ *    a scoped offer.
+ *  - A null/empty judge result means "nothing helpful to say" → silence.
+ *  - The governance gate (cooldowns / cap / dedup / debounce) makes the final
+ *    call and records the emission.
+ */
+export async function decideProactiveComment(input) {
+    const { payload, gate, judge, now } = input;
+    const surface = interactionSurface(payload);
+    if (!surface) {
+        return {
+            text: null,
+            delivery: null,
+            reason: "no surface (policy-silent)",
+        };
+    }
+    if (payload.initiatedBy === "agent") {
+        return {
+            text: null,
+            delivery: null,
+            reason: "agent-initiated (already acknowledged)",
+        };
+    }
+    if (!gate.isSettled(surface, now)) {
+        return {
+            text: null,
+            delivery: null,
+            reason: "debounce: surface not settled",
+        };
+    }
+    const candidate = normalizeProactiveOffer(await judge(payload));
+    if (!candidate) {
+        return {
+            text: null,
+            delivery: null,
+            reason: "judge: nothing helpful to offer",
+        };
+    }
+    const admit = gate.tryAdmit({ surface, text: candidate.text, now });
+    if (!admit.admitted) {
+        return { text: null, delivery: null, reason: admit.reason };
+    }
+    return {
+        text: candidate.text,
+        delivery: candidate.delivery,
+        title: candidate.title,
+        deepLink: candidate.deepLink,
+        groupKey: candidate.groupKey,
+        reason: "admitted",
+    };
+}
+const JUDGE_INSTRUCTION = [
+    "The user just took an action in the app. Decide if there is ONE specific, helpful thing you can proactively offer right now.",
+    'Examples: switched to wallet → "Want me to pull your latest balances?"; opened task-coordinator → "Want me to summarize your open tasks?".',
+    'Use delivery "chat" only when the current view benefits from a visible suggestion. Use delivery "notify" for useful but low-urgency offers that should land quietly outside chat.',
+    "Stay silent (return null) for ambiguous or low-value interactions, settings/config screens, or anything where an offer would be noise.",
+    'Respond as JSON: {"comment": <a short offer, or null>, "delivery": "chat" | "notify", "confidence": 0..1, "urgency": "low" | "medium" | "high", "title": <optional notification title>}.',
+].join("\n");
+/** Describe the interaction for the judge prompt. */
+function describeInteraction(payload) {
+    if ("command" in payload) {
+        return `The user just ran the /${payload.command} command.`;
+    }
+    if ("shortcutId" in payload) {
+        return `The user just used the "${payload.shortcutId}" shortcut.`;
+    }
+    const where = payload.viewLabel ?? payload.viewId;
+    return `The user just opened the ${where} view.`;
+}
+/** Build the small-model judge prompt for an interaction. */
+export function buildProactiveJudgePrompt(payload) {
+    return `${JUDGE_INSTRUCTION}\n${describeInteraction(payload)}`;
+}
+function parseProactiveJudgeObject(raw) {
+    let obj = raw;
+    if (typeof raw === "string") {
+        const trimmed = raw
+            .trim()
+            .replace(/^```(?:json)?\s*/i, "")
+            .replace(/\s*```$/i, "");
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!obj || typeof obj !== "object")
+        return null;
+    return obj;
+}
+function parseOptionalNumber(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw !== "string")
+        return null;
+    const parsed = Number(raw.trim());
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/** Parse the judge model output into a typed offer or null. */
+export function parseProactiveJudgeDecisionOutput(raw) {
+    const obj = parseProactiveJudgeObject(raw);
+    if (!obj)
+        return null;
+    const comment = obj.comment;
+    if (typeof comment !== "string")
+        return null;
+    const trimmed = comment.trim();
+    if (!trimmed || trimmed.toLowerCase() === "none" || trimmed === "null") {
+        return null;
+    }
+    const confidence = parseOptionalNumber(obj.confidence);
+    if (confidence !== null && confidence < 0.65) {
+        return null;
+    }
+    const rawDelivery = obj.delivery ?? obj.channel ?? obj.route;
+    const urgency = typeof obj.urgency === "string" ? obj.urgency.trim().toLowerCase() : "";
+    const delivery = urgency === "low" ||
+        rawDelivery === "notify" ||
+        rawDelivery === "notification"
+        ? "notify"
+        : "chat";
+    const title = typeof obj.title === "string" ? obj.title.trim() : "";
+    const deepLink = typeof obj.deepLink === "string" ? obj.deepLink.trim() : "";
+    const groupKey = typeof obj.groupKey === "string" ? obj.groupKey.trim() : "";
+    return {
+        text: trimmed,
+        delivery,
+        title: title || undefined,
+        deepLink: deepLink || undefined,
+        groupKey: groupKey || undefined,
+    };
+}
+/** Parse the judge model output into an offer string or null. */
+export function parseProactiveJudgeOutput(raw) {
+    return parseProactiveJudgeDecisionOutput(raw)?.text ?? null;
+}
+/**
+ * Subscribe the decider to the runtime event bus. Each VIEW_SWITCHED runs the
+ * small-model judge and, if the governance gate admits, routes the comment.
+ * Fire-and-forget; failures degrade silently (a missed proactive comment must
+ * never break the interaction).
+ */
+export function registerProactiveInteractionDecider(runtime, wiring) {
+    const clock = wiring.now ?? Date.now;
+    // Resolve the live config PER interaction, not once at boot: the user-facing
+    // "Proactive suggestions" control (off/subtle/chatty) writes
+    // ELIZA_PROACTIVE_INTERACTIONS straight to process.env (config-routes), so
+    // re-reading here lets the setting + kill-switch take effect immediately
+    // without a runtime restart. The runtime setting overrides the env default.
+    const resolveConfig = () => {
+        const userSetting = runtime.getSetting(PROACTIVE_CHATTINESS_SETTING_KEY);
+        return resolveProactiveGateConfig(process.env, typeof userSetting === "string" ? userSetting : undefined);
+    };
+    const isSuppressed = () => {
+        try {
+            return wiring.shouldSuppress?.() === true;
+        }
+        catch (err) {
+            logger.debug({ err }, "[proactive-interaction] suppression guard failed");
+            return true;
+        }
+    };
+    const judge = async (payload) => {
+        try {
+            const raw = await runtime.useModel(ModelType.TEXT_SMALL, {
+                prompt: buildProactiveJudgePrompt(payload),
+            });
+            return parseProactiveJudgeDecisionOutput(raw);
+        }
+        catch (err) {
+            logger.debug({ err }, "[proactive-interaction] judge failed");
+            return null;
+        }
+    };
+    const handle = (payload) => {
+        const surface = interactionSurface(payload);
+        if (!surface)
+            return; // policy-silent (e.g. explicit slash commands)
+        if (isSuppressed())
+            return;
+        const config = resolveConfig();
+        wiring.gate.setConfig(config);
+        if (config.chattiness === "off") {
+            logger.debug("[proactive-interaction] suppressed: chattiness=off");
+            return;
+        }
+        wiring.gate.noteSwitch(surface, clock());
+        const run = async () => {
+            try {
+                if (isSuppressed())
+                    return;
+                const decision = await decideProactiveComment({
+                    payload,
+                    gate: wiring.gate,
+                    judge,
+                    now: clock(),
+                });
+                if (decision.text) {
+                    if (isSuppressed())
+                        return;
+                    if (decision.delivery === "notify") {
+                        if (wiring.notify) {
+                            await wiring.notify({
+                                text: decision.text,
+                                delivery: "notify",
+                                title: decision.title,
+                                deepLink: decision.deepLink,
+                                groupKey: decision.groupKey,
+                            });
+                        }
+                        else {
+                            logger.debug("[proactive-interaction] notify delivery requested without notification route");
+                        }
+                    }
+                    else {
+                        await wiring.route(decision.text);
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug({ err }, "[proactive-interaction] decider failed");
+            }
+        };
+        if (config.debounceMs > 0) {
+            setTimeout(() => {
+                void run();
+            }, config.debounceMs);
+        }
+        else {
+            void run();
+        }
+    };
+    // All three interaction events flow through the same governed decider. Slash
+    // commands are consumed but stay silent by policy (see interactionSurface).
+    runtime.registerEvent(EventType.VIEW_SWITCHED, async (payload) => {
+        handle(payload);
+    });
+    runtime.registerEvent(EventType.SHORTCUT_FIRED, async (payload) => {
+        handle(payload);
+    });
+    runtime.registerEvent(EventType.SLASH_COMMAND_INVOKED, async (payload) => {
+        handle(payload);
+    });
+}

package/services/proactive-interaction-gate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Proactive-interaction UX governance gate (#8792).
+ *
+ * The "not annoying" core: turns a stream of UI interactions (view switches,
+ * slash commands, shortcuts) into AT MOST a trickle of proactive comments. Pure
+ * and deterministic — `now` is injected, all state is in-memory — so every rule
+ * (kill-switch, global cooldown, per-surface cooldown, daily cap, textual dedup,
+ * burst debounce) is unit-testable without a runtime or a clock.
+ *
+ * It does NOT decide WHAT to say (that's the model judge) — only WHETHER a
+ * comment is allowed right now. The decider calls {@link tryAdmit} after the
+ * model produced a candidate comment; an admitted call also records the emission
+ * so subsequent calls respect the caps.
+ */
+/** How talkative proactive interaction-comments are. */
+export type ProactiveChattiness = "off" | "subtle" | "chatty";
+export interface ProactiveGateConfig {
+    /** Master verbosity. `off` disables all proactive interaction comments. */
+    chattiness: ProactiveChattiness;
+    /** Minimum gap between ANY two proactive comments. */
+    globalCooldownMs: number;
+    /** Minimum gap before re-commenting on the SAME surface. */
+    perSurfaceCooldownMs: number;
+    /** Hard cap on proactive comments in a rolling 24h window. */
+    dailyCap: number;
+    /** Suppress a comment textually identical to a recent one within this window. */
+    dedupWindowMs: number;
+    /** A surface must be "settled" (no newer switch) this long before commenting. */
+    debounceMs: number;
+}
+/** Tuning per chattiness level. `subtle` is the recommended default for new users. */
+export declare function configForChattiness(chattiness: ProactiveChattiness): ProactiveGateConfig;
+export declare const DEFAULT_PROACTIVE_GATE_CONFIG: ProactiveGateConfig;
+/** Read the kill-switch + chattiness setting from env / user setting. */
+export declare function resolveProactiveChattiness(env?: Record<string, string | undefined>, userSetting?: string | null): ProactiveChattiness;
+export declare function resolveProactiveGateConfig(env?: Record<string, string | undefined>, userSetting?: string | null): ProactiveGateConfig;
+export interface AdmitInput {
+    /** Surface key the comment is about (e.g. a view id). */
+    surface: string;
+    /** The candidate comment text (for dedup). */
+    text: string;
+    now: number;
+}
+export interface AdmitResult {
+    admitted: boolean;
+    reason: string;
+}
+/** In-memory, per-process governance state. */
+export declare class ProactiveInteractionGate {
+    private config;
+    private emissions;
+    /** Latest switch time per surface, for the debounce/settle check. */
+    private lastSwitchAt;
+    /** Most recent switch globally; older surfaces are no longer the settled one. */
+    private latestSwitch;
+    constructor(config?: ProactiveGateConfig);
+    setConfig(config: ProactiveGateConfig): void;
+    /** Record that a surface switch happened (resets its settle timer). */
+    noteSwitch(surface: string, now: number): void;
+    /** True once `debounceMs` has elapsed since the last switch to `surface`. */
+    isSettled(surface: string, now: number): boolean;
+    private pruneOlderThan;
+    /**
+     * Check every gate and, when all pass, record the emission. Returns the first
+     * failing reason so callers can log why a comment was suppressed.
+     */
+    tryAdmit(input: AdmitInput): AdmitResult;
+    reset(): void;
+}
+//# sourceMappingURL=proactive-interaction-gate.d.ts.map

package/services/proactive-interaction-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proactive-interaction-gate.d.ts","sourceRoot":"","sources":["../../src/services/proactive-interaction-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,UAAU,EAAE,mBAAmB,CAAC;IAChC,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,sFAAsF;AACtF,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,mBAAmB,GAC9B,mBAAmB,CA8BrB;AAED,eAAO,MAAM,6BAA6B,EAAE,mBACb,CAAC;AAEhC,yEAAyE;AACzE,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,mBAAmB,CAarB;AAED,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,mBAAmB,CAErB;AAED,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,+CAA+C;AAC/C,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAwB;IACzC,qEAAqE;IACrE,OAAO,CAAC,YAAY,CAA6B;IACjD,iFAAiF;IACjF,OAAO,CAAC,YAAY,CAA6B;gBAErC,MAAM,GAAE,mBAAmD;IAIvE,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAI5C,uEAAuE;IACvE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9C,6EAA6E;IAC7E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAShD,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW;IA8CxC,KAAK,IAAI,IAAI;CAKd"}