@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/notifications/policies/mode-context-policy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Mode-context policy — applies HITL-mode-aware suppression on top of the
+ * base routing decision.
+ *
+ * In `quiet` mode (minimal verbosity), non-critical, non-milestone
+ * notifications that would surface above `panel_only` are suppressed. This
+ * aggressively clears operational churn from the main conversation and
+ * status bar while the user is in a low-interruption session.
+ *
+ * In `balanced` mode, `operational`-tagged `info` notifications are
+ * suppressed but warnings are allowed through (matching the existing default
+ * policy behaviour).
+ *
+ * In `operator` mode, no additional suppression is applied — all
+ * notifications surface as-is.
+ */
+import type { DomainVerbosity, NotificationLevel, NotificationTag, NotificationTarget, RoutingReasonCode } from '../types.js';
+/**
+ * Apply the mode-context suppression policy.
+ *
+ * @param level       - Notification severity level.
+ * @param target      - The routing target resolved by prior policies.
+ * @param tag         - Optional semantic tag classifying the notification.
+ * @param verbosity   - The effective domain verbosity (from HITL preset + overrides).
+ * @returns A RoutingReasonCode for the decision, or undefined if not suppressed.
+ */
+export declare function applyModeContextPolicy(level: NotificationLevel, target: NotificationTarget, tag: NotificationTag | undefined, verbosity: DomainVerbosity): RoutingReasonCode | undefined;
+//# sourceMappingURL=mode-context-policy.d.ts.map

package/dist/_internal/platform/runtime/notifications/policies/mode-context-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-context-policy.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/notifications/policies/mode-context-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAcrB;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,SAAS,EAAE,eAAe,GACzB,iBAAiB,GAAG,SAAS,CA+B/B"}

package/dist/_internal/platform/runtime/notifications/policies/mode-context-policy.js

@@ -0,0 +1,62 @@
+/**
+ * Mode-context policy — applies HITL-mode-aware suppression on top of the
+ * base routing decision.
+ *
+ * In `quiet` mode (minimal verbosity), non-critical, non-milestone
+ * notifications that would surface above `panel_only` are suppressed. This
+ * aggressively clears operational churn from the main conversation and
+ * status bar while the user is in a low-interruption session.
+ *
+ * In `balanced` mode, `operational`-tagged `info` notifications are
+ * suppressed but warnings are allowed through (matching the existing default
+ * policy behaviour).
+ *
+ * In `operator` mode, no additional suppression is applied — all
+ * notifications surface as-is.
+ */
+/**
+ * Tags that are always allowed through regardless of mode.
+ * Milestones and alerts are user-facing events, not operational churn.
+ */
+const ALWAYS_ALLOWED_TAGS = new Set(['milestone', 'alert']);
+/**
+ * Levels that are immune to mode-context suppression.
+ * Critical notifications always surface.
+ */
+const UNSUPPRESSABLE_LEVELS = new Set(['critical']);
+/**
+ * Apply the mode-context suppression policy.
+ *
+ * @param level       - Notification severity level.
+ * @param target      - The routing target resolved by prior policies.
+ * @param tag         - Optional semantic tag classifying the notification.
+ * @param verbosity   - The effective domain verbosity (from HITL preset + overrides).
+ * @returns A RoutingReasonCode for the decision, or undefined if not suppressed.
+ */
+export function applyModeContextPolicy(level, target, tag, verbosity) {
+    // panel_only is already silent — suppression is a no-op.
+    if (target === 'panel_only') {
+        return undefined;
+    }
+    // Critical notifications always surface.
+    if (UNSUPPRESSABLE_LEVELS.has(level)) {
+        return undefined;
+    }
+    // Milestone and alert tags are never suppressed by mode context.
+    if (tag !== undefined && ALWAYS_ALLOWED_TAGS.has(tag)) {
+        return undefined;
+    }
+    // Minimal verbosity: suppress everything except critical/milestone/alert.
+    if (verbosity === 'minimal') {
+        return 'mode_context_minimal';
+    }
+    // Normal verbosity: suppress operational info notifications.
+    if (verbosity === 'normal') {
+        const effectiveTag = tag ?? 'operational';
+        if (level === 'info' && effectiveTag === 'operational') {
+            return 'mode_context_normal';
+        }
+    }
+    // Verbose verbosity: no additional suppression.
+    return undefined;
+}

package/dist/_internal/platform/runtime/notifications/policies/quiet-typing.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Quiet-while-typing policy — suppresses non-critical notifications when
+ * the user is actively composing input, preventing distracting UI churn
+ * mid-keystroke.
+ */
+import type { NotificationLevel, NotificationTarget } from '../types.js';
+/**
+ * Determines if a notification at the given level and target should be
+ * suppressed while the user is actively typing.
+ *
+ * - `critical` — never suppressed
+ * - `warning` / `info` / `debug` — suppressed when quiet mode is active
+ *   AND the resolved target would surface above `panel_only`
+ *
+ * @param level         - Notification severity level.
+ * @param target        - The target resolved by prior policies.
+ * @param quietEnabled  - Whether quiet-while-typing mode is currently active.
+ * @returns Suppression reason string if suppressed, undefined otherwise.
+ */
+export declare function applyQuietTypingPolicy(level: NotificationLevel, target: NotificationTarget, quietEnabled: boolean): string | undefined;
+//# sourceMappingURL=quiet-typing.d.ts.map

package/dist/_internal/platform/runtime/notifications/policies/quiet-typing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quiet-typing.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/notifications/policies/quiet-typing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,kBAAkB,EAC1B,YAAY,EAAE,OAAO,GACpB,MAAM,GAAG,SAAS,CAgBpB"}

package/dist/_internal/platform/runtime/notifications/policies/quiet-typing.js

@@ -0,0 +1,37 @@
+/**
+ * Quiet-while-typing policy — suppresses non-critical notifications when
+ * the user is actively composing input, preventing distracting UI churn
+ * mid-keystroke.
+ */
+/**
+ * Levels that are immune to quiet-while-typing suppression.
+ * Critical notifications always surface regardless of typing state.
+ */
+const UNSUPPRESSABLE_LEVELS = new Set(['critical']);
+/**
+ * Determines if a notification at the given level and target should be
+ * suppressed while the user is actively typing.
+ *
+ * - `critical` — never suppressed
+ * - `warning` / `info` / `debug` — suppressed when quiet mode is active
+ *   AND the resolved target would surface above `panel_only`
+ *
+ * @param level         - Notification severity level.
+ * @param target        - The target resolved by prior policies.
+ * @param quietEnabled  - Whether quiet-while-typing mode is currently active.
+ * @returns Suppression reason string if suppressed, undefined otherwise.
+ */
+export function applyQuietTypingPolicy(level, target, quietEnabled) {
+    if (!quietEnabled) {
+        return undefined;
+    }
+    if (UNSUPPRESSABLE_LEVELS.has(level)) {
+        return undefined;
+    }
+    // Only suppress notifications that would appear above panel_only.
+    // panel_only notifications are already silent; suppressing them is a no-op.
+    if (target === 'panel_only') {
+        return undefined;
+    }
+    return 'quiet_while_typing';
+}

package/dist/_internal/platform/runtime/notifications/router.d.ts

@@ -0,0 +1,139 @@
+/**
+ * NotificationRouter — routes incoming notifications to the appropriate
+ * surface (conversation, status_bar, panel_only) based on level, per-domain
+ * verbosity, quiet-while-typing state, mode-context, burst detection, and
+ * batch policy.
+ *
+ * Policy stack (applied in order):
+ * 1. Default policy        — level + domain verbosity → base target
+ * 2. Quiet-typing policy   — suppresses non-critical above panel_only while typing
+ * 3. Mode-context policy   — HITL-mode-aware suppression (quiet/balanced/operator)
+ * 4. Burst policy          — collapses rapid domain:level event floods
+ * 5. Batch policy          — collapses repeated events within rolling time window
+ *
+ * The `adaptive-notification-suppression` feature flag gates policies 3 and 4.
+ * When the flag is disabled, only the original policies 1, 2, and 5 are applied.
+ */
+import type { DomainVerbosity, Notification, RoutingDecision } from './types.js';
+/**
+ * NotificationRouter applies a layered policy stack to each notification:
+ *
+ * 1. **Default policy** — maps level + domain verbosity to a base target.
+ * 2. **Quiet-typing policy** — suppresses non-critical above panel_only while typing.
+ * 3. **Batch policy** — collapses repeated domain:level pairs within a time window.
+ *
+ * @example
+ * ```ts
+ * const router = createNotificationRouter();
+ * router.setDomainVerbosity('tools', 'minimal');
+ * router.setQuietWhileTyping(true);
+ *
+ * const decision = router.route(notification);
+ * if (decision.reasonCode === 'allowed') {
+ *   deliver(notification, decision.target);
+ * }
+ * ```
+ */
+export declare class NotificationRouter {
+    /** Per-domain configuration (verbosity + optional panel overrides). */
+    private readonly domains;
+    /** Whether quiet-while-typing suppression is active. */
+    private quietWhileTyping;
+    /** Default domain verbosity applied to domains with no explicit config. */
+    private defaultDomainVerbosity;
+    /** Batch deduplication policy instance. */
+    private batchPolicy;
+    /** Burst detection policy instance. */
+    private readonly burstPolicy;
+    /**
+     * Whether the adaptive-notification-suppression feature flag is enabled.
+     * Controls policies 3 (mode-context) and 4 (burst).
+     */
+    private adaptiveSuppression;
+    constructor(batchWindowMs?: number, adaptiveSuppression?: boolean);
+    /**
+     * Route a notification through the full policy stack.
+     *
+     * Returns a RoutingDecision describing where the notification should be
+     * delivered and whether it was suppressed or batched.
+     *
+     * @param notification - The notification to route.
+     * @returns A RoutingDecision with target, reasonCode, optional batchKey,
+     *          and optional suppression reason text.
+     */
+    route(notification: Notification): RoutingDecision;
+    /**
+     * Set the verbosity level for a specific domain.
+     *
+     * @param domain    - Domain name (e.g. 'tools', 'agents', 'git').
+     * @param verbosity - Desired verbosity level.
+     */
+    setDomainVerbosity(domain: string, verbosity: DomainVerbosity): void;
+    /**
+     * Enable or disable quiet-while-typing suppression.
+     *
+     * When enabled, `info` and `warning` notifications that would surface above
+     * `panel_only` are suppressed with reason `'quiet_while_typing'`.
+     * `critical` notifications are never suppressed.
+     *
+     * @param enabled - Whether to activate quiet-while-typing mode.
+     */
+    setQuietWhileTyping(enabled: boolean): void;
+    /**
+     * Set the batch window duration in milliseconds.
+     *
+     * Replaces the current BatchPolicy instance with a fresh one using the
+     * new window. Pending batches from the previous instance are discarded.
+     *
+     * @param ms - Batch window duration in milliseconds.
+     */
+    setBatchWindowMs(ms: number): void;
+    /**
+     * Set the default domain verbosity applied to domains with no explicit config.
+     *
+     * This verbosity is used by `getDomainVerbosity` when a domain has no
+     * per-domain override set via `setDomainVerbosity`.
+     *
+     * @param verbosity - The default verbosity level.
+     */
+    setDefaultDomainVerbosity(verbosity: DomainVerbosity): void;
+    /**
+     * Enable or disable adaptive notification suppression (mode-context + burst policies).
+     *
+     * This corresponds to the `adaptive-notification-suppression` feature flag.
+     * When disabled, only the base default + quiet-typing + batch policies apply.
+     *
+     * @param enabled - Whether to activate adaptive suppression.
+     */
+    setAdaptiveSuppression(enabled: boolean): void;
+    /**
+     * Whether adaptive suppression is currently enabled.
+     */
+    isAdaptiveSuppressionEnabled(): boolean;
+    /**
+     * Flush all pending batched notifications.
+     *
+     * Call this when a batch window expires (e.g. on a periodic timer) or when
+     * quiet-typing mode deactivates, to surface any held notifications.
+     *
+     * @returns Array of notifications (with batch count) that were held in batch groups and are now ready for delivery.
+     */
+    flush(): Array<{
+        notification: Notification;
+        batchCount: number;
+    }>;
+    /**
+     * Returns the active burst group keys from the burst policy.
+     *
+     * Useful at flush time to surface burst summaries.
+     */
+    getActiveBurstGroups(): string[];
+    /**
+     * Resolve the effective domain verbosity, falling back to the default.
+     *
+     * @param domain - Domain name to look up.
+     * @returns Effective DomainVerbosity for the domain.
+     */
+    private getDomainVerbosity;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/_internal/platform/runtime/notifications/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/notifications/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,eAAe,EAChB,MAAM,YAAY,CAAC;AAapB;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAkB;IAC7B,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAE3D,wDAAwD;IACxD,OAAO,CAAC,gBAAgB,CAAS;IAEjC,2EAA2E;IAC3E,OAAO,CAAC,sBAAsB,CAAsC;IAEpE,2CAA2C;IAC3C,OAAO,CAAC,WAAW,CAAc;IAEjC,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAU;gBAGnC,aAAa,CAAC,EAAE,MAAM,EACtB,mBAAmB,GAAE,OAAe;IAYtC;;;;;;;;;OASG;IACH,KAAK,CAAC,YAAY,EAAE,YAAY,GAAG,eAAe;IAuElD;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI;IAKpE;;;;;;;;OAQG;IACH,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI3C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKlC;;;;;;;OAOG;IACH,yBAAyB,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAI3D;;;;;;;OAOG;IACH,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI9C;;OAEG;IACH,4BAA4B,IAAI,OAAO;IAIvC;;;;;;;OAOG;IACH,KAAK,IAAI,KAAK,CAAC;QAAE,YAAY,EAAE,YAAY,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAIlE;;;;OAIG;IACH,oBAAoB,IAAI,MAAM,EAAE;IAMhC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;CAG3B"}

package/dist/_internal/platform/runtime/notifications/router.js

@@ -0,0 +1,222 @@
+/**
+ * NotificationRouter — routes incoming notifications to the appropriate
+ * surface (conversation, status_bar, panel_only) based on level, per-domain
+ * verbosity, quiet-while-typing state, mode-context, burst detection, and
+ * batch policy.
+ *
+ * Policy stack (applied in order):
+ * 1. Default policy        — level + domain verbosity → base target
+ * 2. Quiet-typing policy   — suppresses non-critical above panel_only while typing
+ * 3. Mode-context policy   — HITL-mode-aware suppression (quiet/balanced/operator)
+ * 4. Burst policy          — collapses rapid domain:level event floods
+ * 5. Batch policy          — collapses repeated events within rolling time window
+ *
+ * The `adaptive-notification-suppression` feature flag gates policies 3 and 4.
+ * When the flag is disabled, only the original policies 1, 2, and 5 are applied.
+ */
+import { applyDefaultPolicy } from './policies/default-policy.js';
+import { applyQuietTypingPolicy } from './policies/quiet-typing.js';
+import { applyModeContextPolicy } from './policies/mode-context-policy.js';
+import { BatchPolicy } from './policies/batch-policy.js';
+import { BurstPolicy } from './policies/burst-policy.js';
+/** Default batch window passed through when batchWindowMs is invalid. */
+const DEFAULT_BATCH_WINDOW_MS = 2_000;
+/** Default verbosity applied to domains with no explicit configuration. */
+const DEFAULT_VERBOSITY = 'normal';
+/**
+ * NotificationRouter applies a layered policy stack to each notification:
+ *
+ * 1. **Default policy** — maps level + domain verbosity to a base target.
+ * 2. **Quiet-typing policy** — suppresses non-critical above panel_only while typing.
+ * 3. **Batch policy** — collapses repeated domain:level pairs within a time window.
+ *
+ * @example
+ * ```ts
+ * const router = createNotificationRouter();
+ * router.setDomainVerbosity('tools', 'minimal');
+ * router.setQuietWhileTyping(true);
+ *
+ * const decision = router.route(notification);
+ * if (decision.reasonCode === 'allowed') {
+ *   deliver(notification, decision.target);
+ * }
+ * ```
+ */
+export class NotificationRouter {
+    /** Per-domain configuration (verbosity + optional panel overrides). */
+    domains = new Map();
+    /** Whether quiet-while-typing suppression is active. */
+    quietWhileTyping = false;
+    /** Default domain verbosity applied to domains with no explicit config. */
+    defaultDomainVerbosity = DEFAULT_VERBOSITY;
+    /** Batch deduplication policy instance. */
+    batchPolicy;
+    /** Burst detection policy instance. */
+    burstPolicy;
+    /**
+     * Whether the adaptive-notification-suppression feature flag is enabled.
+     * Controls policies 3 (mode-context) and 4 (burst).
+     */
+    adaptiveSuppression;
+    constructor(batchWindowMs, adaptiveSuppression = false) {
+        const effectiveMs = batchWindowMs !== undefined
+            ? Math.max(1, Number.isFinite(batchWindowMs) ? batchWindowMs : DEFAULT_BATCH_WINDOW_MS)
+            : undefined;
+        this.batchPolicy = new BatchPolicy(effectiveMs);
+        this.burstPolicy = new BurstPolicy();
+        this.adaptiveSuppression = adaptiveSuppression;
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Route a notification through the full policy stack.
+     *
+     * Returns a RoutingDecision describing where the notification should be
+     * delivered and whether it was suppressed or batched.
+     *
+     * @param notification - The notification to route.
+     * @returns A RoutingDecision with target, reasonCode, optional batchKey,
+     *          and optional suppression reason text.
+     */
+    route(notification) {
+        const verbosity = this.getDomainVerbosity(notification.domain);
+        // 1. Apply default level-based routing policy.
+        const baseTarget = applyDefaultPolicy(notification.level, verbosity);
+        // 2. Apply quiet-while-typing suppression.
+        const quietReason = applyQuietTypingPolicy(notification.level, baseTarget, this.quietWhileTyping);
+        if (quietReason !== undefined) {
+            return {
+                target: baseTarget,
+                suppressed: quietReason,
+                reasonCode: 'quiet_while_typing',
+            };
+        }
+        // 3. Apply mode-context suppression (gated by adaptive-notification-suppression flag).
+        if (this.adaptiveSuppression) {
+            const modeReasonCode = applyModeContextPolicy(notification.level, baseTarget, notification.tag, verbosity);
+            if (modeReasonCode !== undefined) {
+                return {
+                    target: 'panel_only',
+                    suppressed: modeReasonCode,
+                    reasonCode: modeReasonCode,
+                };
+            }
+            // 4. Apply burst detection policy (exempt critical, milestone, and alert — they always surface).
+            if (notification.level !== 'critical'
+                && notification.tag !== 'milestone'
+                && notification.tag !== 'alert') {
+                const burstKey = this.burstPolicy.evaluate(notification);
+                if (burstKey !== undefined) {
+                    return {
+                        target: 'panel_only',
+                        batchKey: burstKey,
+                        reasonCode: 'burst_collapsed',
+                    };
+                }
+            }
+        }
+        // 5. Apply batch deduplication policy (exempt critical — they always surface).
+        if (notification.level !== 'critical') {
+            const batchKey = this.batchPolicy.evaluate(notification);
+            if (batchKey !== undefined) {
+                // Notification collapsed into a batch group — route silently to panel.
+                return {
+                    target: 'panel_only',
+                    batchKey,
+                    reasonCode: 'batch_window_collapsed',
+                };
+            }
+        }
+        return { target: baseTarget, reasonCode: 'allowed' };
+    }
+    /**
+     * Set the verbosity level for a specific domain.
+     *
+     * @param domain    - Domain name (e.g. 'tools', 'agents', 'git').
+     * @param verbosity - Desired verbosity level.
+     */
+    setDomainVerbosity(domain, verbosity) {
+        const existing = this.domains.get(domain);
+        this.domains.set(domain, { ...existing, verbosity });
+    }
+    /**
+     * Enable or disable quiet-while-typing suppression.
+     *
+     * When enabled, `info` and `warning` notifications that would surface above
+     * `panel_only` are suppressed with reason `'quiet_while_typing'`.
+     * `critical` notifications are never suppressed.
+     *
+     * @param enabled - Whether to activate quiet-while-typing mode.
+     */
+    setQuietWhileTyping(enabled) {
+        this.quietWhileTyping = enabled;
+    }
+    /**
+     * Set the batch window duration in milliseconds.
+     *
+     * Replaces the current BatchPolicy instance with a fresh one using the
+     * new window. Pending batches from the previous instance are discarded.
+     *
+     * @param ms - Batch window duration in milliseconds.
+     */
+    setBatchWindowMs(ms) {
+        const effectiveMs = Math.max(1, Number.isFinite(ms) ? ms : DEFAULT_BATCH_WINDOW_MS);
+        this.batchPolicy = new BatchPolicy(effectiveMs);
+    }
+    /**
+     * Set the default domain verbosity applied to domains with no explicit config.
+     *
+     * This verbosity is used by `getDomainVerbosity` when a domain has no
+     * per-domain override set via `setDomainVerbosity`.
+     *
+     * @param verbosity - The default verbosity level.
+     */
+    setDefaultDomainVerbosity(verbosity) {
+        this.defaultDomainVerbosity = verbosity;
+    }
+    /**
+     * Enable or disable adaptive notification suppression (mode-context + burst policies).
+     *
+     * This corresponds to the `adaptive-notification-suppression` feature flag.
+     * When disabled, only the base default + quiet-typing + batch policies apply.
+     *
+     * @param enabled - Whether to activate adaptive suppression.
+     */
+    setAdaptiveSuppression(enabled) {
+        this.adaptiveSuppression = enabled;
+    }
+    /**
+     * Whether adaptive suppression is currently enabled.
+     */
+    isAdaptiveSuppressionEnabled() {
+        return this.adaptiveSuppression;
+    }
+    /**
+     * Flush all pending batched notifications.
+     *
+     * Call this when a batch window expires (e.g. on a periodic timer) or when
+     * quiet-typing mode deactivates, to surface any held notifications.
+     *
+     * @returns Array of notifications (with batch count) that were held in batch groups and are now ready for delivery.
+     */
+    flush() {
+        return this.batchPolicy.flush();
+    }
+    /**
+     * Returns the active burst group keys from the burst policy.
+     *
+     * Useful at flush time to surface burst summaries.
+     */
+    getActiveBurstGroups() {
+        return this.burstPolicy.getActiveGroups();
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    /**
+     * Resolve the effective domain verbosity, falling back to the default.
+     *
+     * @param domain - Domain name to look up.
+     * @returns Effective DomainVerbosity for the domain.
+     */
+    getDomainVerbosity(domain) {
+        return this.domains.get(domain)?.verbosity ?? this.defaultDomainVerbosity;
+    }
+}

package/dist/_internal/platform/runtime/notifications/types.d.ts

@@ -0,0 +1,127 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Notification system types — core interfaces for the conversation noise
+ * routing model. Operational noise is routed to dedicated
+ * panels; the main conversation receives only critical failures, milestones,
+ * and condensed summaries.
+ */
+/** Severity level of a notification. Controls routing priority. */
+export type NotificationLevel = 'critical' | 'warning' | 'info' | 'debug';
+/**
+ * Surface target for a routed notification.
+ * - `conversation` — inline in the main conversation (high-signal only)
+ * - `status_bar`   — ephemeral status bar display
+ * - `panel_only`   — routed silently to a dedicated panel
+ */
+export type NotificationTarget = 'conversation' | 'status_bar' | 'panel_only';
+/**
+ * Per-domain verbosity setting.
+ * - `minimal` — only critical notifications surface above panel_only
+ * - `normal`  — warnings surface to conversation/status_bar
+ * - `verbose` — info notifications also surface above panel_only
+ */
+export type DomainVerbosity = 'minimal' | 'normal' | 'verbose';
+/**
+ * Typed reason codes for routing decisions.
+ *
+ * These codes appear in RoutingDecision.reasonCode and provide a machine-
+ * readable explanation of why a notification was suppressed or redirected.
+ *
+ * - `allowed`                — notification was not suppressed (delivered normally)
+ * - `quiet_while_typing`     — suppressed because the user is actively typing
+ * - `mode_context_minimal`   — suppressed by the mode-context policy (quiet/minimal mode)
+ * - `mode_context_normal`    — suppressed by the mode-context policy (normal mode, operational info)
+ * - `burst_collapsed`        — collapsed into an existing burst batch group
+ * - `batch_window_collapsed` — collapsed by the rolling batch-window policy
+ * - `domain_verbosity_low`   — domain verbosity set below the notification level
+ */
+export type RoutingReasonCode = 'allowed' | 'quiet_while_typing' | 'mode_context_minimal' | 'mode_context_normal' | 'burst_collapsed' | 'batch_window_collapsed' | 'domain_verbosity_low';
+/**
+ * Semantic tag classifying a notification's operational role.
+ *
+ * Used by the burst and mode-context policies to distinguish high-signal
+ * events from operational churn:
+ * - `operational` — routine progress / heartbeat events (most suppressible)
+ * - `milestone`   — meaningful completion or state-change events
+ * - `alert`       — user-attention-required events (least suppressible)
+ */
+export type NotificationTag = 'operational' | 'milestone' | 'alert';
+/** An action that can be triggered when the user interacts with a notification. */
+export interface NotificationAction {
+    /** Human-readable label (e.g. "Jump to panel"). */
+    label: string;
+    /** The type of action to perform. */
+    type: 'jump_to_panel' | 'dismiss' | 'custom';
+    /** Panel ID to focus when type is `jump_to_panel`. */
+    panelId?: string;
+    /** Arbitrary payload for `custom` action types. */
+    payload?: Record<string, unknown>;
+}
+/** A single notification to be routed and potentially displayed. */
+export interface Notification {
+    /** Unique identifier for this notification. */
+    id: string;
+    /**
+     * Domain that produced this notification (e.g. 'tools', 'agents',
+     * 'session', 'git'). Used for per-domain verbosity and routing policy.
+     */
+    domain: string;
+    /** Severity level — determines base routing target. */
+    level: NotificationLevel;
+    /** Short human-readable title. */
+    title: string;
+    /** Optional extended body text. */
+    body?: string;
+    /** Unix timestamp in milliseconds when the notification was created. */
+    timestamp: number;
+    /** Panel ID that should display this notification when routed to panel_only. */
+    panelId?: string;
+    /** Optional action (e.g. jump to panel) presented alongside the notification. */
+    action?: NotificationAction;
+    /**
+     * Optional semantic tag classifying the notification's operational role.
+     * When absent, the notification is treated as `operational` by default.
+     */
+    tag?: NotificationTag;
+}
+/**
+ * The result of routing a single notification.
+ * Contains the target surface and optional metadata about batching/suppression.
+ */
+export interface RoutingDecision {
+    /** The surface where this notification should be delivered. */
+    target: NotificationTarget;
+    /**
+     * Batch group key when this notification has been collapsed into a batch.
+     * Consumers should coalesce all notifications sharing the same batchKey.
+     */
+    batchKey?: string;
+    /**
+     * When set, this notification was suppressed and should not be displayed.
+     * The string value describes the suppression reason (e.g. 'quiet_while_typing').
+     */
+    suppressed?: string;
+    /**
+     * Structured reason code for this routing decision.
+     * Always present; reflects the final policy that determined the outcome.
+     */
+    reasonCode: RoutingReasonCode;
+}
+/** A notification paired with its routing decision. */
+export interface RoutedNotification {
+    /** The original notification. */
+    notification: Notification;
+    /** The routing decision applied to it. */
+    decision: RoutingDecision;
+}
+/**
+ * Per-domain routing configuration, merging domain verbosity with any
+ * domain-specific panel target overrides.
+ */
+export interface DomainConfig {
+    /** Verbosity level controlling how aggressively noise is suppressed. */
+    verbosity: DomainVerbosity;
+    /** Override the default panel target for panel_only notifications. */
+    defaultPanelId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/runtime/notifications/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/notifications/types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;GAKG;AAEH,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,YAAY,GAAG,YAAY,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,oBAAoB,GACpB,sBAAsB,GACtB,qBAAqB,GACrB,iBAAiB,GACjB,wBAAwB,GACxB,sBAAsB,CAAC;AAE3B;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,OAAO,CAAC;AAEpE,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,IAAI,EAAE,eAAe,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC7C,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,EAAE,iBAAiB,CAAC;IACzB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,SAAS,EAAE,eAAe,CAAC;IAC3B,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/_internal/platform/runtime/notifications/types.js

@@ -0,0 +1,2 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export {};