switchroom 0.19.27 → 0.19.29

package/dist/cli/autoaccept-poll.js

@@ -295,6 +295,182 @@ function queryPendingPermission(agentName, opts = {}) {
   });
 }
 
+// telegram-plugin/flood-circuit-breaker.ts
+import {
+  existsSync,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2,
+  mkdirSync as mkdirSync2,
+  chmodSync as chmodSync2,
+  unlinkSync as unlinkSync2,
+  renameSync
+} from "node:fs";
+import { dirname as dirname2, join as join3 } from "node:path";
+
+// telegram-plugin/flood-429-ledger.ts
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+var FLOOD_429_LEDGER_FILE = "429-ledger.json";
+var FLOOD_429_LEDGER_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+var PENALTY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+var TRIVIAL_PRESSURE_WINDOW_MS = 24 * 60 * 60 * 1000;
+function flood429LedgerPath(stateDir) {
+  return join2(stateDir, FLOOD_429_LEDGER_FILE);
+}
+function parseEpisode(raw) {
+  if (typeof raw !== "object" || raw === null)
+    return null;
+  const r = raw;
+  const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+  const firstTs = num(r.firstTs);
+  const untilTs = num(r.untilTs);
+  const peak = num(r.peakRetryAfterSec);
+  if (firstTs === null || untilTs === null || peak === null)
+    return null;
+  return {
+    firstTs,
+    lastTs: num(r.lastTs) ?? firstTs,
+    peakRetryAfterSec: peak,
+    untilTs,
+    count: num(r.count) ?? 1
+  };
+}
+function readFlood429LedgerResult(path, readFile = (p) => readFileSync(p, "utf-8")) {
+  let text;
+  try {
+    text = readFile(path);
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return { status: "absent", episodes: [] };
+    return {
+      status: "unreadable",
+      episodes: [],
+      error: `${code ?? "EUNKNOWN"}: ${err?.message ?? String(err)}`
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return { status: "corrupt", episodes: [], error: err?.message ?? String(err) };
+  }
+  if (!Array.isArray(parsed)) {
+    return { status: "corrupt", episodes: [], error: "ledger is not a JSON array" };
+  }
+  const out = [];
+  let dropped = 0;
+  for (const raw of parsed) {
+    const ep = parseEpisode(raw);
+    if (ep)
+      out.push(ep);
+    else
+      dropped += 1;
+  }
+  if (dropped > 0 && out.length === 0) {
+    return { status: "corrupt", episodes: [], error: `${dropped} unparseable entr(ies)` };
+  }
+  return { status: "ok", episodes: out };
+}
+
+// telegram-plugin/flood-circuit-breaker.ts
+var blindLoggedAt = new Map;
+var FLOOD_WINDOWS_FILE = "flood-windows.json";
+function floodWindowsPath(stateDir) {
+  return join3(stateDir, FLOOD_WINDOWS_FILE);
+}
+var FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS = 5 * 60000;
+function readFloodWindows(path, now, log = (l) => process.stderr.write(l)) {
+  if (!existsSync(path))
+    return [];
+  const failSafe = (why) => {
+    log(`telegram gateway: flood-breaker: scoped-windows file ${path} is ${why} \u2014 ` + `failing SAFE: opening a conservative ${FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS}ms global ` + `window rather than booting into a possible open ban with no windows (issue #3106)
+`);
+    return [
+      {
+        scopeKey: "global",
+        untilTs: now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
+        retryAfterSrc: `failsafe:${why}`,
+        observedAt: now
+      }
+    ];
+  };
+  let text;
+  try {
+    text = readFileSync2(path, "utf-8");
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return [];
+    return failSafe(`unreadable (${code ?? "error"})`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return failSafe("corrupt (invalid JSON)");
+  }
+  if (!Array.isArray(raw))
+    return failSafe("corrupt (not an array)");
+  const out = [];
+  for (const r of raw) {
+    const rec = r;
+    if (typeof rec.scopeKey !== "string" || typeof rec.untilTs !== "number")
+      continue;
+    if (rec.untilTs <= now)
+      continue;
+    out.push({
+      scopeKey: rec.scopeKey,
+      untilTs: rec.untilTs,
+      retryAfterSrc: typeof rec.retryAfterSrc === "string" ? rec.retryAfterSrc : "unknown",
+      observedAt: typeof rec.observedAt === "number" ? rec.observedAt : now,
+      ...typeof rec.alertedAt === "number" ? { alertedAt: rec.alertedAt } : {}
+    });
+  }
+  return out;
+}
+
+// src/agents/flood-pressure-probe.ts
+var FLOOD_PRESSURE_GRACE_MS = 120000;
+function scopeBlocksCardDelivery(scopeKey) {
+  return !scopeKey.startsWith("msg-edit:");
+}
+var NO_PRESSURE = { active: false, reason: "" };
+function resolveTelegramStateDir() {
+  return process.env.TELEGRAM_STATE_DIR ?? "/state/agent/telegram";
+}
+function readFloodPressure(now, opts = {}) {
+  const stateDir = opts.stateDir ?? resolveTelegramStateDir();
+  const graceMs = opts.graceMs ?? FLOOD_PRESSURE_GRACE_MS;
+  try {
+    const windows = readFloodWindows(floodWindowsPath(stateDir), now - graceMs, () => {});
+    for (const w of windows) {
+      if (!scopeBlocksCardDelivery(w.scopeKey))
+        continue;
+      const msLeft = w.untilTs - now;
+      return {
+        active: true,
+        reason: msLeft > 0 ? `open flood window ${w.scopeKey} (${Math.ceil(msLeft / 1000)}s left, src=${w.retryAfterSrc})` : `flood window ${w.scopeKey} closed ${Math.ceil(-msLeft / 1000)}s ago (within ${Math.round(graceMs / 1000)}s grace)`
+      };
+    }
+    const ledger = readFlood429LedgerResult(flood429LedgerPath(stateDir));
+    if (ledger.status === "ok") {
+      for (const ep of ledger.episodes) {
+        const lastEvidenceTs = Math.max(ep.lastTs, ep.untilTs);
+        if (lastEvidenceTs >= now - graceMs) {
+          return {
+            active: true,
+            reason: `429 episode ${ep.count}x peak=${ep.peakRetryAfterSec}s last seen ` + `${Math.max(0, Math.round((now - ep.lastTs) / 1000))}s ago ` + `(within ${Math.round(graceMs / 1000)}s grace)`
+          };
+        }
+      }
+    }
+    return NO_PRESSURE;
+  } catch {
+    return NO_PRESSURE;
+  }
+}
+
 // src/agents/wedge-watchdog.ts
 var WEDGE_FOOTER_SIGNATURE = /(?=[\s\S]*[Ee]sc(?:ape)?[^\n]*cancel)(?=[\s\S]*(?:to select|to navigate|\u2191\/\u2193))/;
 var RATE_LIMIT_MENU_SIGNATURE = /(?=[\s\S]*Stop and wait for)(?=[\s\S]*(?:usage credits|Upgrade your plan|\/rate-limit-options))/;
@@ -438,6 +614,8 @@ var DEFAULT_COOLDOWN_MS = 60000;
 var DEFAULT_CONFIRM_MODAL_POLLS = 3;
 var DEFAULT_MANIFEST_STALL_POLLS = 60;
 var DEFAULT_PERMISSION_PROMPT_POLLS = 3;
+var DEFAULT_PERMISSION_CARDLESS_POLLS = 24;
+var DEFAULT_PERMISSION_FLOOD_MAX_POLLS = 120;
 function envInt(name, fallback) {
   const raw = process.env[name];
   if (raw === undefined || raw.trim() === "")
@@ -467,6 +645,9 @@ async function runWedgeWatchdog(opts) {
   const confirmModalPolls = opts.confirmModalPolls ?? envInt("SWITCHROOM_WEDGE_CONFIRM_POLLS", DEFAULT_CONFIRM_MODAL_POLLS);
   const permissionPromptSignature = opts.permissionPromptSignature === null ? null : opts.permissionPromptSignature ?? PERMISSION_PROMPT_SIGNATURE;
   const permissionPromptPolls = opts.permissionPromptPolls ?? envInt("SWITCHROOM_WEDGE_PERMISSION_POLLS", DEFAULT_PERMISSION_PROMPT_POLLS);
+  const permissionCardlessPolls = Math.max(permissionPromptPolls, opts.permissionCardlessPolls ?? envInt("SWITCHROOM_WEDGE_PERMISSION_CARDLESS_POLLS", DEFAULT_PERMISSION_CARDLESS_POLLS));
+  const floodPressure = opts.floodPressure === null ? null : opts.floodPressure ?? ((n) => readFloodPressure(n));
+  const permissionFloodMaxPolls = Math.max(permissionCardlessPolls, opts.permissionFloodMaxPolls ?? envInt("SWITCHROOM_WEDGE_PERMISSION_FLOOD_MAX_POLLS", DEFAULT_PERMISSION_FLOOD_MAX_POLLS));
   const manifestStallSignature = opts.manifestStallSignature === null ? null : opts.manifestStallSignature ?? MANIFESTING_SIGNATURE;
   const manifestStallPolls = opts.manifestStallPolls ?? envInt("SWITCHROOM_WEDGE_MANIFEST_POLLS", DEFAULT_MANIFEST_STALL_POLLS);
   const requestRestart = opts.requestRestart;
@@ -485,6 +666,8 @@ async function runWedgeWatchdog(opts) {
   let confirmModalFires = 0;
   let permissionPromptFires = 0;
   let permissionPromptDeferrals = 0;
+  let permissionPromptFloodHolds = 0;
+  let permissionPromptCardlessHolds = 0;
   let restartEscalations = 0;
   let polls = 0;
   let confirmModalPresent = 0;
@@ -493,6 +676,7 @@ async function runWedgeWatchdog(opts) {
   let lastManifestKey = null;
   let confirmCooldownUntil = 0;
   let permissionCooldownUntil = 0;
+  let lastPermissionHoldLogAt = Number.NEGATIVE_INFINITY;
   while (polls < maxPolls) {
     polls++;
     let text = "";
@@ -602,17 +786,37 @@ async function runWedgeWatchdog(opts) {
           permissionPromptDeferrals++;
           permissionCooldownUntil = now() + cooldownMs;
         } else {
-          const reason = queryPendingPermission2 == null ? "card-aware check disabled" : status && status.ok ? "gateway reports no pending permission (card-less prompt)" : `gateway unreachable/no answer within budget${status && !status.ok ? ` (${status.reason})` : ""}`;
-          console.error(`[wedge-watchdog] ${opts.agentName}: dismissing stuck per-tool ` + `permission prompt (Esc == decline == safe DENY) after ` + `${permissionPromptPresent} polls present ` + `(~${Math.round(permissionPromptPresent * pollIntervalMs / 1000)}s) \u2014 ${reason}`);
-          try {
-            send(opts.agentName, ["Escape"]);
-          } catch (err) {
-            console.error(`[wedge-watchdog] ${opts.agentName}: send threw: ${err.message}`);
+          const held = now();
+          const pressure = floodPressure ? floodPressure(held) : null;
+          const logHold = (line) => {
+            if (held - lastPermissionHoldLogAt < cooldownMs)
+              return;
+            lastPermissionHoldLogAt = held;
+            console.error(line);
+          };
+          const floodHold = pressure?.active === true && permissionPromptPresent < permissionFloodMaxPolls;
+          const cardless = status != null && status.ok && !status.pending;
+          const cardlessHold = !floodHold && cardless && permissionPromptPresent < permissionCardlessPolls;
+          if (floodHold) {
+            permissionPromptFloodHolds++;
+            logHold(`[wedge-watchdog] ${opts.agentName}: permission prompt present ` + `${permissionPromptPresent} polls ` + `(~${Math.round(permissionPromptPresent * pollIntervalMs / 1000)}s) but ` + `Telegram is flood-throttling this agent (${pressure.reason}) \u2014 ` + `an approval card may be deferred, NOT sending Esc ` + `(ceiling ${permissionFloodMaxPolls} polls)`);
+          } else if (cardlessHold) {
+            permissionPromptCardlessHolds++;
+            logHold(`[wedge-watchdog] ${opts.agentName}: gateway reports no pending ` + `permission after ${permissionPromptPresent} polls ` + `(~${Math.round(permissionPromptPresent * pollIntervalMs / 1000)}s) \u2014 ` + `holding Esc until the card-less streak of ${permissionCardlessPolls} polls ` + `(~${Math.round(permissionCardlessPolls * pollIntervalMs / 1000)}s), ` + `in case the card is merely late`);
+          } else {
+            const reason = queryPendingPermission2 == null ? "card-aware check disabled" : status && status.ok ? `gateway reports no pending permission (card-less prompt) for ${permissionCardlessPolls}+ polls` : `gateway unreachable/no answer within budget${status && !status.ok ? ` (${status.reason})` : ""}`;
+            const floodNote = pressure?.active ? ` [flood ceiling ${permissionFloodMaxPolls} polls reached while ${pressure.reason}]` : "";
+            console.error(`[wedge-watchdog] ${opts.agentName}: dismissing stuck per-tool ` + `permission prompt (Esc == decline == safe DENY) after ` + `${permissionPromptPresent} polls present ` + `(~${Math.round(permissionPromptPresent * pollIntervalMs / 1000)}s) \u2014 ${reason}${floodNote}`);
+            try {
+              send(opts.agentName, ["Escape"]);
+            } catch (err) {
+              console.error(`[wedge-watchdog] ${opts.agentName}: send threw: ${err.message}`);
+            }
+            fires++;
+            permissionPromptFires++;
+            permissionCooldownUntil = now() + cooldownMs;
+            permissionPromptPresent = 0;
           }
-          fires++;
-          permissionPromptFires++;
-          permissionCooldownUntil = now() + cooldownMs;
-          permissionPromptPresent = 0;
         }
       }
     } else if (isConfirmModal) {
@@ -667,6 +871,8 @@ async function runWedgeWatchdog(opts) {
     confirmModalFires,
     permissionPromptFires,
     permissionPromptDeferrals,
+    permissionPromptFloodHolds,
+    permissionPromptCardlessHolds,
     restartEscalations,
     polls,
     reason: "max-polls"
@@ -675,10 +881,10 @@ async function runWedgeWatchdog(opts) {
 
 // src/agents/rate-limit-signal.ts
 import { createConnection as createConnection2 } from "node:net";
-import { join as join2 } from "node:path";
+import { join as join4 } from "node:path";
 function resolveGatewaySocketPath2() {
   const stateDir = process.env.TELEGRAM_STATE_DIR ?? "/state/agent/telegram";
-  return process.env.SWITCHROOM_GATEWAY_SOCKET ?? join2(stateDir, "gateway.sock");
+  return process.env.SWITCHROOM_GATEWAY_SOCKET ?? join4(stateDir, "gateway.sock");
 }
 function signalQuotaWall(agentName, resetAt, opts = {}) {
   const socketPath = opts.socketPath ?? resolveGatewaySocketPath2();
@@ -744,7 +950,7 @@ function signalQuotaWall(agentName, resetAt, opts = {}) {
 import * as net from "node:net";
 import { homedir } from "node:os";
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { join as join3 } from "node:path";
+import { join as join5 } from "node:path";
 
 // node_modules/.bun/zod@3.25.76/node_modules/zod/v3/external.js
 var exports_external = {};
@@ -5031,7 +5237,7 @@ function reviveDate(v) {
   return Number.isNaN(d.getTime()) ? null : d;
 }
 function operatorSocketPath(home = homedir()) {
-  return join3(home, ".switchroom", "state", "auth-broker-operator", "sock");
+  return join5(home, ".switchroom", "state", "auth-broker-operator", "sock");
 }
 function resolveAuthBrokerSocketPath(opts) {
   if (opts?.socket)
@@ -5406,8 +5612,9 @@ async function main() {
   const rateLimitDetect = process.env.SWITCHROOM_RATE_LIMIT_DETECT !== "0";
   const overageSelect = rateLimitDetect && process.env.SWITCHROOM_RATE_LIMIT_OVERAGE !== "0";
   const permissionCardAware = process.env.SWITCHROOM_PERMISSION_CARD_AWARE !== "0";
+  const permissionFloodAware = process.env.SWITCHROOM_WEDGE_FLOOD_AWARE !== "0";
   try {
-    console.error(`[autoaccept-poll] ${agentName}: entering wedge-watchdog (continuous)` + (rateLimitDetect ? " +rate-limit-detect" : " (rate-limit-detect OFF)") + (overageSelect ? " +overage-carveout" : "") + (permissionCardAware ? " +permission-card-aware" : " (permission-card-aware OFF)"));
+    console.error(`[autoaccept-poll] ${agentName}: entering wedge-watchdog (continuous)` + (rateLimitDetect ? " +rate-limit-detect" : " (rate-limit-detect OFF)") + (overageSelect ? " +overage-carveout" : "") + (permissionCardAware ? " +permission-card-aware" : " (permission-card-aware OFF)") + (permissionFloodAware ? " +permission-flood-aware" : " (permission-flood-aware OFF)"));
     const res = await runWedgeWatchdog({
       agentName,
       rateLimitSignature: rateLimitDetect ? undefined : null,
@@ -5416,9 +5623,10 @@ async function main() {
       } : undefined,
       overageDecision: overageSelect ? () => queryActiveOverageServing() : undefined,
       requestRestart: requestWedgeRestart,
-      queryPendingPermission: permissionCardAware ? undefined : null
+      queryPendingPermission: permissionCardAware ? undefined : null,
+      floodPressure: permissionFloodAware ? undefined : null
     });
-    console.error(`[autoaccept-poll] ${agentName}: wedge-watchdog returned reason=${res.reason} fires=${res.fires} rateLimitFires=${res.rateLimitFires} overageCreditSelections=${res.overageCreditSelections} confirmModalFires=${res.confirmModalFires} permissionPromptFires=${res.permissionPromptFires} permissionPromptDeferrals=${res.permissionPromptDeferrals} restartEscalations=${res.restartEscalations}`);
+    console.error(`[autoaccept-poll] ${agentName}: wedge-watchdog returned reason=${res.reason} fires=${res.fires} rateLimitFires=${res.rateLimitFires} overageCreditSelections=${res.overageCreditSelections} confirmModalFires=${res.confirmModalFires} permissionPromptFires=${res.permissionPromptFires} permissionPromptDeferrals=${res.permissionPromptDeferrals} permissionPromptFloodHolds=${res.permissionPromptFloodHolds} permissionPromptCardlessHolds=${res.permissionPromptCardlessHolds} restartEscalations=${res.restartEscalations}`);
   } catch (err) {
     console.error(`[autoaccept-poll] ${agentName}: wedge-watchdog unexpected throw: ${err.message}`);
   }

package/dist/cli/notion-write-pretool.mjs

@@ -11718,6 +11718,16 @@ init_zod();
 
 // src/config/schema.ts
 init_zod();
+
+// src/memory/observation-scopes.ts
+var OBSERVATION_SCOPES = [
+  "per_tag",
+  "combined",
+  "all_combinations",
+  "shared"
+];
+
+// src/config/schema.ts
 var CodeRepoEntrySchema = exports_external.object({
   name: exports_external.string().describe("Short alias used when claiming (e.g. 'switchroom')"),
   source: exports_external.string().describe("Absolute or home-relative path to the repo (e.g. ~/code/switchroom)"),
@@ -11829,6 +11839,7 @@ var AgentToolsSchema = exports_external.object({
   allow: exports_external.array(exports_external.string()).default([]).describe("Allowed tools (use ['all'] for unrestricted)"),
   deny: exports_external.array(exports_external.string()).default([]).describe("Denied tools (overrides allow)")
 }).optional();
+var ObservationScopesSchema = exports_external.enum(OBSERVATION_SCOPES).optional().describe("Per-row observation scope stamped on every memory this agent " + `retains. "shared" makes Hindsight's consolidation write the ` + "resulting observations into ONE global untagged scope instead of a " + "scope per tag \u2014 what several agents pooling one bank need so their " + "observations actually merge rather than sitting in parallel " + "per-tag silos. OMITTED BY DEFAULT: unset means the field never goes " + "on the wire and the engine's own default stands, which is the " + "shipped behaviour. Applies to every retain path (Stop hook, " + "sidechain, boot reconcile, queue drain, backfill, session-handoff " + "mirror) and is carried on the queued payload, so a retain that fails " + "now and drains later still lands in this scope. Accepted values: " + `${OBSERVATION_SCOPES.join(", ")}. ` + "Cascade: override (per-agent wins over default).");
 var AgentMemorySchema = exports_external.object({
   collection: exports_external.string().describe("Hindsight collection name for this agent"),
   auto_recall: exports_external.boolean().default(true).describe("Auto-search memories before each response"),
@@ -11863,6 +11874,7 @@ var AgentMemorySchema = exports_external.object({
     empathy: exports_external.number().int().min(1).max(5).optional().describe("How much the bank weights emotional/relational context (1-5; engine default 3).")
   }).optional().describe("Personality traits (1-5 each) steering how this bank frames recall, " + "reflect, and observation synthesis \u2014 a coach leans empathy-high, a " + "lawyer/analyst leans skepticism/literalism-high. Maps to the engine's " + "flat `disposition_skepticism`/`_literalism`/`_empathy` fields. " + "Cascade: per-key merge (an agent overrides individual traits and " + "inherits the rest, matching `recall`)."),
   directive_capture_nudge: exports_external.boolean().optional().describe("Deterministic directive-capture nudge (issue #2848 Stage B). When " + "on (switchroom default true \u2014 Stage A measured a ~55% miss rate on " + "durable corrections), the auto-recall hook regex-detects correction " + '/ standing-rule-shaped inbound ("always/never \u2026", "from now on \u2026", ' + `"stop doing \u2026", a stated preference, "that's wrong, it's \u2026") and ` + "appends a terse advisory to the turn's context telling the model to " + "persist the rule with mcp__hindsight__create_directive if it IS " + "durable. Detection is pure regex \u2014 the model does the judgment " + "in-session and calls create_directive itself (no model callsite, no " + "silent hook-side write). Set false to disable per-agent. " + "Cascade: override (per-agent wins over default)."),
+  observation_scopes: ObservationScopesSchema,
   recall: exports_external.object({
     max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
     cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
@@ -12106,7 +12118,10 @@ var LiteLLMConfigSchema = exports_external.object({
   admin_key: exports_external.string().optional().describe("LiteLLM master/admin key used at apply time to provision the team + " + "virtual key. Supports a vault reference (e.g. " + "'vault:litellm/master-key') \u2014 resolution happens at apply time via " + "the vault-broker. Never injected into the agent container."),
   team: exports_external.string().optional().describe("LiteLLM team alias the per-agent key is created under. Defaults to " + "'switchroom' (applied in code, not as a schema default)."),
   small_fast_model: exports_external.string().optional().describe("Model id exported as ANTHROPIC_SMALL_FAST_MODEL for the claude CLI's " + "background/fast lane, e.g. 'claude-haiku-4-5-20251001'."),
-  tags: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Extra key/value metadata tags attached to the provisioned LiteLLM " + "virtual key. Merged per-key across cascade layers (agent wins).")
+  tags: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Extra key/value metadata tags attached to the provisioned LiteLLM " + "virtual key. Merged per-key across cascade layers (agent wins)."),
+  max_budget: exports_external.number().positive().optional().describe("HARD spend cap in USD for this agent's virtual key over one " + "`budget_duration` window. LiteLLM refuses the request once the key's " + "tracked spend exceeds it, so a runaway loop costs at most this much " + "before it is stopped. Defaults to " + "DEFAULT_KEY_MAX_BUDGET_USD (see src/litellm/budget.ts) \u2014 deliberately " + "conservative; raise it per-agent rather than removing it. Set 0 or " + "omit `budget_duration` at your own risk: an uncapped key is only as " + "bounded as the upstream account balance."),
+  soft_budget: exports_external.number().positive().optional().describe("ADVISORY spend threshold in USD. LiteLLM keeps serving past it and " + "raises a budget alert instead. Must be < max_budget. NOTE: LiteLLM " + "accepts soft_budget only on POST /key/generate (GenerateKeyRequest); " + "UpdateKeyRequest does NOT carry it, so changing this value only takes " + "effect on a key that is (re)generated, not on an existing one."),
+  budget_duration: exports_external.string().regex(/^\d+(s|m|h|d|mo)$/, "budget_duration must be a LiteLLM duration like '30d', '24h', '1mo'").optional().describe("Rolling window the budget resets on, in LiteLLM duration syntax " + "('30d', '24h', '1mo'). Defaults to DEFAULT_KEY_BUDGET_DURATION. " + "WITHOUT a duration LiteLLM treats max_budget as a LIFETIME cap that " + "never resets \u2014 the key silently dies for good once it is hit.")
 }).optional().describe("LiteLLM routing config \u2014 opt-in per-agent virtual-key auto-provisioning " + "+ routing env. Default OFF. See LiteLLMConfigSchema doc for the full flow.");
 var HindsightPerOpLlmSchema = exports_external.object({
   model: exports_external.string().min(1).optional().describe("Per-op model (upstream `HINDSIGHT_API_<OP>_LLM_MODEL`). Absent \u2192 " + "inherit the global `hindsight.llm.model`."),
@@ -12125,7 +12140,7 @@ var HindsightConfigSchema = exports_external.object({
     reflect: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `reflect` LLM op (synthesis / mental-model " + "refresh). Emits `HINDSIGHT_API_REFLECT_LLM_*`. Absent \u2192 uses global."),
     consolidation: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `consolidation` LLM op (background memory " + "merge). Emits `HINDSIGHT_API_CONSOLIDATION_LLM_*`. Absent \u2192 global.")
   }).optional().describe("LLM knob for the hindsight container. The flat `provider`/`model` set " + "the global default (backward-compatible); optional `retain`/`reflect`/" + "`consolidation` blocks override individual ops. All fields optional; " + "unset fields fall back to the hard-coded defaults."),
-  env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_MAX_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
+  env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_MAX_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND, RECENCY_DECAY_FUNCTION, " + "RECENCY_DECAY_HALFLIFE_DAYS \u2014 switchroom defaults recall's recency " + "curve to `exponential` with a 30-day half-life so a fact retained " + "today outranks a stale one, instead of upstream's near-flat " + "linear/365-day window), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap; and " + "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS \u2014 only read when the " + "decay function is `linear`, so switchroom ships no default for it but " + "still honours an operator who flips the function back; and " + "HINDSIGHT_API_WORKER_MAX_SLOTS \u2014 the worker poller's TOTAL in-flight " + "task budget, the pool WORKER_CONSOLIDATION_MAX_SLOTS reserves out of; " + "unset means upstream's own default; and " + "HINDSIGHT_API_WORKER_RETAIN_MAX_SLOTS \u2014 the reserved slot FLOOR for the " + "retain (memory write) lane, carved from that same total; unset means " + "upstream's own 0, i.e. no floor and retain competes for the shared " + "pool), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
 });
 var MicrosoftWorkspaceConfigSchema = exports_external.object({
   microsoft_client_id: exports_external.string().min(1).optional().describe("Microsoft OAuth application (client) ID from Entra portal " + "(literal string or vault reference e.g. " + "'vault:microsoft-oauth-client-id'). OPTIONAL \u2014 omit it to use " + "switchroom's shipped default Microsoft app (zero-config). " + "Set it only to bring your own Entra app (BYO)."),
@@ -12258,6 +12273,7 @@ var profileFields = {
     file: exports_external.boolean().optional(),
     isolation: exports_external.enum(["default", "strict"]).optional(),
     directive_capture_nudge: exports_external.boolean().optional(),
+    observation_scopes: ObservationScopesSchema,
     recall: exports_external.object({
       max_memories: exports_external.number().int().min(0).optional(),
       cache_ttl_secs: exports_external.number().int().min(0).optional(),