@agent-native/core 0.144.3 → 0.145.1

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7847
+- template files: 7848

package/corpus/templates/clips/changelog/2026-08-06-desktop-full-screen-recordings-now-normalize-microphone-leve.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-06
+---
+
+Desktop full-screen recordings now normalize microphone level while recording, so clips are no longer quieter than the rest of your library.

package/corpus/templates/clips/desktop/src-tauri/src/native_screen/custom_capture.rs

@@ -2145,6 +2145,175 @@ const MIX_SOURCE_GRACE: Duration = Duration::from_millis(2000);
 const AUDIO_FORMAT_LPCM: u32 = 0x6C70_636D; // 'lpcm'
 const AUDIO_FORMAT_FLAGS_FLOAT_PACKED: u32 = 1 | 8; // float + packed, interleaved, little-endian
 
+/// Speech RMS the mic auto-gain aims for (~-20 dBFS), and how far it may
+/// travel to get there. It never attenuates: a hot mic keeps its own level
+/// and the limiter below owns peak safety.
+const MIC_AGC_TARGET_RMS: f32 = 0.1;
+const MIC_AGC_MIN_GAIN: f32 = 1.0;
+const MIC_AGC_MAX_GAIN: f32 = 8.0; // +18 dB
+/// Below this RMS the mic is between words: hold the current gain rather than
+/// chasing the target, or every pause swells room tone to speech level.
+///
+/// Set at ~-60 dBFS, not the -50 dBFS that room tone alone would justify. A
+/// quiet built-in MacBook mic — the whole reason this stage exists — can carry
+/// speech at -45 dBFS RMS, and a floor set just under that would gate out the
+/// exact signal it is supposed to lift. Worst case here is room tone amplified
+/// to 0.001 × MIC_AGC_MAX_GAIN, still inaudible.
+const MIC_AGC_NOISE_FLOOR_RMS: f32 = 0.001;
+const MIC_AGC_ENVELOPE_SECONDS: f32 = 0.15;
+/// Asymmetric: back off quickly when the mic gets loud (the limiter should be
+/// a backstop, not the thing shaping the sound), return slowly so a boost
+/// doesn't audibly pump across sentences.
+const MIC_AGC_DUCK_SECONDS: f32 = 0.08;
+const MIC_AGC_BOOST_SECONDS: f32 = 1.5;
+/// Until the first speech has been levelled, converge at this rate instead of
+/// `MIC_AGC_BOOST_SECONDS`. Gain starts at unity, so a quiet mic needs to
+/// travel most of its range; at the steady-state rate that takes several
+/// seconds and the opening sentence audibly swells.
+const MIC_AGC_WARMUP_SECONDS: f32 = 0.2;
+/// How close to the target counts as levelled and ends the warmup.
+const MIC_AGC_CONVERGED_TOLERANCE: f32 = 0.05;
+/// -1.0 dBFS, near the true-peak ceiling the offline loudnorm chain targets.
+const MIX_LIMIT_CEILING: f32 = 0.891;
+const MIX_LIMIT_RELEASE_SECONDS: f32 = 0.15;
+
+/// One-pole smoothing coefficient for a time constant at the mixer's rate.
+///
+/// `exp_m1`, not `1.0 - exp(x)`: at 48 kHz the exponent is ~1e-5, so the
+/// subtraction form cancels away most of the f32 mantissa and the longer time
+/// constants come out with about three significant digits.
+fn one_pole_coefficient(tau_seconds: f32, sample_rate: i32) -> f32 {
+    if tau_seconds <= 0.0 || sample_rate <= 0 {
+        return 1.0;
+    }
+    -(-1.0 / (tau_seconds * sample_rate as f32)).exp_m1()
+}
+
+/// Causal mic auto-gain.
+///
+/// ScreenCaptureKit captures without AGC — unlike the browser path, which gets
+/// one from `autoGainControl` — so a MacBook mic lands far below the -16 LUFS
+/// the offline chain in `native_screen.rs` normalizes to. Live-uploaded clips
+/// never reach that chain: their bytes stream to the server while the writer
+/// is still producing them, so nothing downstream can re-read the file. Gain
+/// has to be decided here, from what has already been heard.
+struct MicAutoGain {
+    mean_square: f32,
+    gain: f32,
+    /// False until the first speech has been levelled; see
+    /// `MIC_AGC_WARMUP_SECONDS`.
+    levelled: bool,
+    envelope_coefficient: f32,
+    warmup_coefficient: f32,
+    duck_coefficient: f32,
+    boost_coefficient: f32,
+}
+
+impl MicAutoGain {
+    fn new(sample_rate: i32) -> Self {
+        Self {
+            mean_square: 0.0,
+            gain: 1.0,
+            levelled: false,
+            envelope_coefficient: one_pole_coefficient(MIC_AGC_ENVELOPE_SECONDS, sample_rate),
+            warmup_coefficient: one_pole_coefficient(MIC_AGC_WARMUP_SECONDS, sample_rate),
+            duck_coefficient: one_pole_coefficient(MIC_AGC_DUCK_SECONDS, sample_rate),
+            boost_coefficient: one_pole_coefficient(MIC_AGC_BOOST_SECONDS, sample_rate),
+        }
+    }
+
+    fn next_gain(&mut self, left: f32, right: f32) -> f32 {
+        let peak = left.abs().max(right.abs());
+        self.mean_square += (peak * peak - self.mean_square) * self.envelope_coefficient;
+        let rms = self.mean_square.max(0.0).sqrt();
+        if rms >= MIC_AGC_NOISE_FLOOR_RMS {
+            let target = (MIC_AGC_TARGET_RMS / rms).clamp(MIC_AGC_MIN_GAIN, MIC_AGC_MAX_GAIN);
+            let coefficient = if !self.levelled {
+                self.warmup_coefficient
+            } else if target < self.gain {
+                self.duck_coefficient
+            } else {
+                self.boost_coefficient
+            };
+            self.gain += (target - self.gain) * coefficient;
+            if !self.levelled && (self.gain - target).abs() <= target * MIC_AGC_CONVERGED_TOLERANCE
+            {
+                self.levelled = true;
+                // Once per recording. A "clip is too quiet" report is only
+                // diagnosable if the log says what the mic measured and how
+                // much was added; `gain` pinned at MIC_AGC_MAX_GAIN means the
+                // cap, not the target, decided the level.
+                crate::logfile::diagnostic(&format!(
+                    "[capture-health] mic auto-gain levelled: rms={rms:.6} gain={:.2} capped={}",
+                    self.gain,
+                    self.gain >= MIC_AGC_MAX_GAIN * 0.99
+                ));
+            }
+        }
+        self.gain
+    }
+}
+
+/// Zero-latency peak limiter over the summed mix.
+///
+/// This replaces a flat 0.5x weight on each source, which bought clip safety
+/// by discarding 6 dB whether or not anything was near full scale. Lookahead
+/// would buy cleaner transients but costs an output delay, and the live
+/// uploader has already streamed the frames preceding it.
+struct PeakLimiter {
+    gain: f32,
+    release_coefficient: f32,
+}
+
+impl PeakLimiter {
+    fn new(sample_rate: i32) -> Self {
+        Self {
+            gain: 1.0,
+            release_coefficient: one_pole_coefficient(MIX_LIMIT_RELEASE_SECONDS, sample_rate),
+        }
+    }
+
+    fn next_gain(&mut self, peak: f32) -> f32 {
+        self.gain += (1.0 - self.gain) * self.release_coefficient;
+        if peak > MIX_LIMIT_CEILING {
+            self.gain = self.gain.min(MIX_LIMIT_CEILING / peak);
+        }
+        self.gain
+    }
+}
+
+/// The mixer's whole gain stage: auto-gain the mic, sum with system audio at
+/// unity, limit the result. Kept separate from `LiveAudioMixer` so the mix rule
+/// is reachable without constructing a `CMFormatDescription` — the reported bug
+/// was a wrong per-frame weight, so that arithmetic is what needs covering.
+struct MixGainStage {
+    mic: MicAutoGain,
+    limiter: PeakLimiter,
+}
+
+impl MixGainStage {
+    fn new(sample_rate: i32) -> Self {
+        Self {
+            mic: MicAutoGain::new(sample_rate),
+            limiter: PeakLimiter::new(sample_rate),
+        }
+    }
+
+    /// One output frame. Neither source is pre-attenuated: system audio passes
+    /// at unity and the mic is only ever boosted, with the limiter owning peak
+    /// safety for the sum.
+    fn frame(&mut self, system: (f32, f32), mic: (f32, f32)) -> (f32, f32) {
+        let mic_gain = self.mic.next_gain(mic.0, mic.1);
+        let left = system.0 + mic.0 * mic_gain;
+        let right = system.1 + mic.1 * mic_gain;
+        let limit = self.limiter.next_gain(left.abs().max(right.abs()));
+        (
+            (left * limit).clamp(-1.0, 1.0),
+            (right * limit).clamp(-1.0, 1.0),
+        )
+    }
+}
+
 #[derive(Clone, Copy, PartialEq, Eq)]
 /// Which capture stream a pushed PCM chunk came from.
 enum MixSource {
@@ -2224,63 +2393,6 @@ impl MixerTimeline {
     }
 }
 
-#[cfg(test)]
-mod mixer_timeline_tests {
-    use super::MixerTimeline;
-
-    fn stereo_frames(values: &[f32]) -> Vec<f32> {
-        values.iter().flat_map(|value| [*value, *value]).collect()
-    }
-
-    #[test]
-    fn trims_overlapping_frames_instead_of_extending_the_timeline() {
-        let mut timeline = MixerTimeline::new();
-        timeline.push_at(0, &stereo_frames(&[1.0, 2.0, 3.0, 4.0]), 0, 96_000);
-        timeline.push_at(3, &stereo_frames(&[4.0, 5.0, 6.0, 7.0]), 0, 96_000);
-
-        assert_eq!(
-            timeline.samples,
-            stereo_frames(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0])
-        );
-        assert_eq!(timeline.end_frame(), 7);
-    }
-
-    #[test]
-    fn ignores_fully_duplicated_buffers() {
-        let mut timeline = MixerTimeline::new();
-        let frames = stereo_frames(&[1.0, 2.0, 3.0]);
-        timeline.push_at(0, &frames, 0, 96_000);
-        timeline.push_at(0, &frames, 0, 96_000);
-
-        assert_eq!(timeline.samples, frames);
-        assert_eq!(timeline.end_frame(), 3);
-    }
-
-    #[test]
-    fn trims_input_that_starts_behind_already_emitted_output() {
-        let mut timeline = MixerTimeline::new();
-        timeline.started = true;
-        timeline.base_frame = 10;
-        timeline.push_at(8, &stereo_frames(&[1.0, 2.0, 3.0, 4.0]), 10, 96_000);
-
-        assert_eq!(timeline.samples, stereo_frames(&[3.0, 4.0]));
-        assert_eq!(timeline.end_frame(), 12);
-    }
-
-    #[test]
-    fn preserves_forward_timestamp_gaps_as_silence() {
-        let mut timeline = MixerTimeline::new();
-        timeline.push_at(0, &stereo_frames(&[1.0, 2.0]), 0, 96_000);
-        timeline.push_at(5, &stereo_frames(&[6.0]), 0, 96_000);
-
-        assert_eq!(
-            timeline.samples,
-            stereo_frames(&[1.0, 2.0, 0.0, 0.0, 0.0, 6.0])
-        );
-        assert_eq!(timeline.end_frame(), 6);
-    }
-}
-
 enum SourceBound {
     /// Started and recently fed; bounds output to `end_frame`.
     Active(i64),
@@ -2313,6 +2425,9 @@ struct LiveAudioMixer {
     out_pos: i64,
     system: MixerTimeline,
     mic: MixerTimeline,
+    /// Gain stage, carried across chunks: emitted frames are already uploaded,
+    /// so its state is the only memory the mix has.
+    gain: MixGainStage,
     created_at: Instant,
 }
 
@@ -2360,6 +2475,7 @@ impl LiveAudioMixer {
             out_pos: 0,
             system: MixerTimeline::new(),
             mic: MixerTimeline::new(),
+            gain: MixGainStage::new(sample_rate),
             created_at: Instant::now(),
         })
     }
@@ -2465,15 +2581,14 @@ impl LiveAudioMixer {
     }
 
     /// Emit mixed sample buffers covering `out_pos..safe_end` in
-    /// `MIX_CHUNK_FRAMES` chunks: average system + mic per frame, clamp, wrap
-    /// as LPCM `CMSampleBuffer`s with contiguous PTS.
+    /// `MIX_CHUNK_FRAMES` chunks: auto-gain the mic, sum with system audio,
+    /// limit, wrap as LPCM `CMSampleBuffer`s with contiguous PTS.
     ///
-    /// Each source is weighted at 0.5 before summing so that two full-scale
-    /// signals (which occurs when a USB audio interface with software monitoring
-    /// routes the mic back through system audio) can never exceed ±1.0 and
-    /// hard-clip. The standard SCK pipeline applies the same 0.5×L + 0.5×R
-    /// pan-downmix for the same reason; loudnorm restores the target loudness
-    /// in post-processing.
+    /// Clip safety belongs to `PeakLimiter`, not to a fixed weight per source.
+    /// Two full-scale signals do occur — a USB interface with software
+    /// monitoring routes the mic back through system audio — but attenuating
+    /// every frame for that case is what left live-uploaded clips ~6 dB below
+    /// the rest, with no post-processing stage left to make it back up.
     fn drain_ready(
         &mut self,
         flush: bool,
@@ -2493,10 +2608,11 @@ impl LiveAudioMixer {
             let mut interleaved = vec![0.0_f32; n * 2];
             for f in 0..n {
                 let frame = a + f as i64;
-                let (sl, sr) = self.system.sample_at(frame);
-                let (ml, mr) = self.mic.sample_at(frame);
-                interleaved[f * 2] = (sl * 0.5 + ml * 0.5).clamp(-1.0, 1.0);
-                interleaved[f * 2 + 1] = (sr * 0.5 + mr * 0.5).clamp(-1.0, 1.0);
+                let (left, right) = self
+                    .gain
+                    .frame(self.system.sample_at(frame), self.mic.sample_at(frame));
+                interleaved[f * 2] = left;
+                interleaved[f * 2 + 1] = right;
             }
             emitted.push(self.build_sample_buffer(&interleaved, a)?);
             a = b;

package/corpus/templates/design/app/components/design/MultiScreenCanvas.tsx

@@ -182,6 +182,19 @@ const MAX_WHEEL_PAN_DELTA = 140;
 const CHROME_SCALE_CSS_VAR = "--an-chrome-scale";
 const PIXEL_GRID_ZOOM = 800;
 
+function hasScreenChildLayers(content: string): boolean {
+  const body = content.match(/<body\b[^>]*>([\s\S]*?)<\/body\s*>/i)?.[1] ?? "";
+  const editableMarkup = body
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(
+      /<(script|style|template)\b[^>]*>[\s\S]*?<\/\1\s*>|<(link|meta|base)\b[^>]*>/gi, // i18n-ignore regex removes non-rendered document elements
+      "",
+    )
+    .trim();
+
+  return editableMarkup.length > 0;
+}
+
 import {
   BOARD_SURFACE_BACKGROUND,
   getBoardContentKey,
@@ -3430,6 +3443,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       const originCanvas = getCanvasPoint(e.clientX, e.clientY);
       let latestRect = normalizeRectFromPoints(originCanvas, originCanvas);
       let layerCandidates: CanvasLayerMarqueeCandidate[] = [];
+      let lastLayerSelectionSignature: string | null = null;
       const marqueeState: MarqueeDragState = {
         type: "marquee",
         originClient: { x: e.clientX, y: e.clientY },
@@ -3469,6 +3483,14 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             screenId: candidate.screenId,
             info: candidate.info,
           }));
+        const signature = selection
+          .map(
+            (item) =>
+              `${item.screenId}:${item.info.sourceId ?? item.info.pendingNodeId ?? item.info.selector ?? item.info.id ?? ""}`,
+          )
+          .join("|");
+        if (signature === lastLayerSelectionSignature) return;
+        lastLayerSelectionSignature = signature;
         onLayerMarqueeSelectionChange?.(selection, {
           source: "marquee",
           additive: state.additive,
@@ -3513,6 +3535,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           additive: false,
           shiftKey: false,
         });
+        lastLayerSelectionSignature = "";
       }
       setIsDragging(true);
       // Seed collection with whatever the zero-size origin rect already
@@ -8236,6 +8259,9 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             onStartRotate={(event) =>
               beginRotate(singleSelectedFrame.id, event)
             }
+            onStartDrag={(event) =>
+              beginFrameDrag(singleSelectedFrame.id, event)
+            }
           />
         ) : null}
 
@@ -8259,6 +8285,9 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             chromeScale={chromeScale}
             chromeSettling={chromeSettling}
             handlesEnabled={!readOnly}
+            onStartDrag={(event) =>
+              beginFrameDrag(selectedFrameEntries[0]!.id, event)
+            }
             onStartResize={beginGroupResize}
             onStartRotate={beginGroupRotate}
           />
@@ -8270,6 +8299,9 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             chromeScale={chromeScale}
             chromeSettling={chromeSettling}
             handlesEnabled={!readOnly}
+            onStartDrag={(event) =>
+              beginDraftDrag(selectedDraftEntries[0]!.id, event)
+            }
             onStartResize={beginDraftGroupResize}
           />
         ) : null}
@@ -9563,6 +9595,7 @@ const Screen = memo(function Screen({
     !suppressFrameChromeForChild;
   const screenContentInteractive =
     Boolean(screenContent) &&
+    (isSelected || hasScreenChildLayers(screen.content)) &&
     !locked &&
     !penActive &&
     !creationToolActive &&
@@ -9771,16 +9804,14 @@ const Screen = memo(function Screen({
         role="button"
         tabIndex={0}
         onClick={(e) => {
-          if (isInteractiveScreenContentTarget(e.target)) {
-            e.stopPropagation();
-            return;
-          }
+          const interactiveContent = isInteractiveScreenContentTarget(e.target);
           e.stopPropagation();
           if (suppressNextClick.current) {
             suppressNextClick.current = false;
             return;
           }
           if (e.detail > 1) return;
+          if (interactiveContent && isSelected) return;
           onPick(screen.id, e);
         }}
         onDoubleClick={(e) => {
@@ -10672,6 +10703,7 @@ function GroupSelectionBox({
   bounds,
   chromeScale,
   chromeSettling,
+  onStartDrag,
   onStartResize,
   onStartRotate,
   handlesEnabled = true,
@@ -10679,6 +10711,7 @@ function GroupSelectionBox({
   bounds: NonNullable<ReturnType<typeof getFrameGroupBounds>>;
   chromeScale: number;
   chromeSettling: boolean;
+  onStartDrag?: (e: React.MouseEvent) => void;
   onStartResize: (handle: ResizeHandle, e: React.MouseEvent) => void;
   /** Multi-selection rotate (CV14). Omit to keep the previous behavior (no
    *  rotate handle shown) — used by callers whose selection kind doesn't
@@ -10699,6 +10732,7 @@ function GroupSelectionBox({
       showRotate={!!onStartRotate}
       handlesEnabled={handlesEnabled}
       filled
+      onStartDrag={onStartDrag}
       onStartResize={onStartResize}
       onStartRotate={onStartRotate ?? (() => {})}
     />
@@ -10765,6 +10799,7 @@ function SelectionBox({
   handlesEnabled = true,
   onStartResize,
   onStartRotate,
+  onStartDrag,
 }: {
   geometry: FrameGeometry;
   chromeScale: number;
@@ -10774,6 +10809,7 @@ function SelectionBox({
   handlesEnabled?: boolean;
   onStartResize: (handle: ResizeHandle, e: React.MouseEvent) => void;
   onStartRotate: (e: React.MouseEvent) => void;
+  onStartDrag?: (e: React.MouseEvent) => void;
 }) {
   return (
     <div
@@ -10798,6 +10834,13 @@ function SelectionBox({
         zIndex: 1_000_000,
       }}
     >
+      {onStartDrag ? (
+        <span
+          data-frame-drag-surface
+          className="pointer-events-auto absolute inset-0 z-[5] cursor-move"
+          onMouseDown={onStartDrag}
+        />
+      ) : null}
       <ResizeHandles
         active
         enabled={handlesEnabled}

package/corpus/templates/forms/server/plugins/agent-chat.ts

@@ -56,7 +56,7 @@ export default createAgentChatPlugin({
   actions: loadActionsFromStaticRegistry(actionsRegistry),
   nativeActionsInDev: true,
   skipFilesContext: true,
-  databaseTools: false,
+  frameworkTools: { database: "off" },
   resolveOrgId: async (event) => (await getOrgContext(event)).orgId,
   mentionProviders: async () => {
     const { getDb } = await import("../db/index.js");

package/corpus/templates/slides/server/plugins/agent-chat.ts

@@ -43,7 +43,7 @@ export default createAgentChatPlugin({
   // Customer and product activity data belongs to Analytics. Keep raw DB
   // tools out of both the interactive and A2A Slides agent surfaces so the
   // agent cannot bypass the Analytics data dictionary with local SQL.
-  databaseTools: "off",
+  frameworkTools: { database: "off" },
   // Enable sandboxed JavaScript execution so Slides agents can fetch,
   // paginate, and reduce provider data through providerFetch() without us
   // hardcoding one action per Google Drive endpoint.

package/dist/agent/production-agent.d.ts

@@ -196,6 +196,12 @@ export interface ActionEntry {
      * `needsApproval` option. See `packages/core/docs/content/actions.mdx`.
      */
     needsApproval?: boolean | ((args: any, ctx?: import("../action.js").ActionRunContext) => boolean | Promise<boolean>);
+    /** Which framework tool group contributed this action. Set by the framework,
+     *  never by an app: apps own their action names, and a tagged action is one
+     *  the app can switch off wholesale through `frameworkTools`. Tagged actions
+     *  are also excluded from the DEFAULT first-request tool list — they stay
+     *  reachable through `tool-search` unless named in `initialToolNames`. */
+    frameworkGroup?: import("../framework-tools.js").FrameworkToolGroup;
 }
 /** @deprecated Use `ActionEntry` instead */
 export type ScriptEntry = ActionEntry;

package/dist/agent/run-manager.d.ts

@@ -181,13 +181,56 @@ export declare const SQL_SUBSCRIPTION_IDLE_POLL_MS = 500;
 export declare const SQL_SUBSCRIPTION_ACTIVE_GRACE_MS = 2000;
 /** Keep terminal/status probes at the historical cadence to bound DB work. */
 export declare const SQL_SUBSCRIPTION_STATUS_POLL_MS = 500;
+/**
+ * Consecutive empty polls before the IDLE cadence starts decaying toward
+ * `SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS`.
+ *
+ * The active grace already covers a streaming producer, so decay only ever
+ * applies to a subscriber watching a run that is producing nothing: a long tool
+ * call, a slow first token, or a wedged producer. Those cost one poll per
+ * 500ms each, forever, per subscriber — the single largest source of idle
+ * `agent_run_events` reads.
+ */
+export declare const SQL_SUBSCRIPTION_IDLE_DECAY_AFTER_POLLS = 4;
+/**
+ * Ceiling for the decayed idle cadence. Bounds the WORST-CASE added latency to
+ * the next token a quiet run eventually produces; a row already waiting when the
+ * timer fires is delivered immediately, so this is not added to a streaming run.
+ */
+export declare const SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS = 2000;
+/**
+ * Cadence for the opportunistic `reapIfStale` probe inside the SSE poll loop,
+ * kept SEPARATE from (and much slower than) the status probe next to it.
+ *
+ * A reap can only ever act on a run whose liveness basis is older than the
+ * tightest staleness window any sweep enforces — `RUN_STALE_MS`, 15s — so
+ * running it on the 500ms status cadence issued ~30 rounds of
+ * `reconcileTerminalRunFromEvents` + reap-eligibility queries (2-4 round trips
+ * each) before the first one could possibly match a row. This cadence still
+ * detects a stale producer well inside the client's own idle timeout while
+ * cutting that probe traffic ~10x. `getRunById` deliberately stays on the fast
+ * status cadence: it is one indexed read and it is what closes the stream on a
+ * NORMAL finish, which must stay prompt.
+ */
+export declare const SQL_SUBSCRIPTION_REAP_POLL_MS = 5000;
 /** Initial retry delay after a transient cross-isolate SQL polling failure. */
 export declare const SQL_SUBSCRIPTION_RETRY_BASE_MS = 250;
 /** Bound consecutive SQL polling failures so a dead subscription fails loud. */
 export declare const SQL_SUBSCRIPTION_MAX_CONSECUTIVE_FAILURES = 4;
 /** Cap retry delay even if the failure bound changes independently. */
 export declare const SQL_SUBSCRIPTION_RETRY_MAX_MS = 2000;
-export declare function resolveSqlSubscriptionPollMs(now: number, activePollUntil: number): number;
+export declare function resolveSqlSubscriptionPollMs(now: number, activePollUntil: number, consecutiveEmptyPolls?: number): number;
+/**
+ * Advance the empty-poll counter that drives `resolveSqlSubscriptionPollMs`'s
+ * decay.
+ *
+ * Only IDLE polls count. Counting the ~16 fast polls inside the active grace
+ * window would push the ladder to its cap the instant the grace expired, so a
+ * producer that pauses a few seconds between tokens would resume at the 2s cap
+ * instead of 500ms — a visible mid-stream stutter rather than the intended
+ * "this run has gone quiet" backoff.
+ */
+export declare function nextSqlSubscriptionEmptyPolls(current: number, hadEvents: boolean, now: number, activePollUntil: number): number;
 export declare function resolveSqlSubscriptionRetryMs(consecutiveFailures: number): number;
 export interface StartRunOptions {
     /** Keep a request-scoped serverless invocation alive for this run. */