@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/config/schemas/memory-substrate.ts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+
+import { WEIGHT_SUM_TOLERANCE } from "./memory-v2.js";
+
+/**
+ * Memory substrate (shared concept-page infrastructure) tuning.
+ *
+ * Every key is optional with no default: an unset key resolves to its
+ * historical `memory.v2` counterpart via `resolveSubstrateTuning` (the
+ * substrate's single config choke point), so the v2 schema keeps supplying
+ * the effective defaults. `spread_k`, `spread_hops`, and
+ * `ann_candidate_limit` map onto `memory.v2.k`, `memory.v2.hops`, and
+ * `memory.v2.ann_candidate_limit` respectively; every other key shares its
+ * name with its `memory.v2` twin.
+ */
+export const MemorySubstrateConfigSchema = z
+  .object({
+    sweep_enabled: z
+      .boolean({ error: "memory.substrate.sweep_enabled must be a boolean" })
+      .optional()
+      .describe(
+        "Whether the idle-debounced memory sweep job is enabled. `remember()` is the primary capture path; opt in only when the model is missing entries the sweep would have caught.",
+      ),
+    dense_weight: z
+      .number({ error: "memory.substrate.dense_weight must be a number" })
+      .min(0, "memory.substrate.dense_weight must be >= 0")
+      .max(1, "memory.substrate.dense_weight must be <= 1")
+      .optional()
+      .describe(
+        "Weight on dense (cosine) similarity in the hybrid retrieval score.",
+      ),
+    sparse_weight: z
+      .number({ error: "memory.substrate.sparse_weight must be a number" })
+      .min(0, "memory.substrate.sparse_weight must be >= 0")
+      .max(1, "memory.substrate.sparse_weight must be <= 1")
+      .optional()
+      .describe(
+        "Weight on sparse (BM25-style) similarity in the hybrid retrieval score — sparse acts as a discriminator for keyword-rich queries.",
+      ),
+    min_sparse_spread: z
+      .number({ error: "memory.substrate.min_sparse_spread must be a number" })
+      .min(0, "memory.substrate.min_sparse_spread must be >= 0")
+      .max(1, "memory.substrate.min_sparse_spread must be <= 1")
+      .optional()
+      .describe(
+        "Adaptive sparse weighting: when the spread (max - min) of normalized sparse scores across the candidate hit set falls below this, sparse contribution collapses to 0. Linear interpolation between this and `full_sparse_spread`. Optional escape hatch — leave unset to use the built-in default.",
+      ),
+    full_sparse_spread: z
+      .number({ error: "memory.substrate.full_sparse_spread must be a number" })
+      .min(0, "memory.substrate.full_sparse_spread must be >= 0")
+      .max(1, "memory.substrate.full_sparse_spread must be <= 1")
+      .optional()
+      .describe(
+        "Adaptive sparse weighting: at or above this spread, sparse weight stays at the configured `sparse_weight`. Optional escape hatch — leave unset to use the built-in default.",
+      ),
+    bm25_k1: z
+      .number({ error: "memory.substrate.bm25_k1 must be a number" })
+      .min(0, "memory.substrate.bm25_k1 must be >= 0")
+      .optional()
+      .describe(
+        "BM25 term-frequency saturation parameter. Increase to make repeated mentions of a term matter more, decrease to flatten the curve.",
+      ),
+    bm25_b: z
+      .number({ error: "memory.substrate.bm25_b must be a number" })
+      .min(0, "memory.substrate.bm25_b must be >= 0")
+      .max(1, "memory.substrate.bm25_b must be <= 1")
+      .optional()
+      .describe(
+        "BM25 document-length normalization. 0 disables length normalization, 1 fully normalizes. Concept-page collections include structured list pages with high information density per word, so values below Lucene's 0.75 default avoid over-penalizing them.",
+      ),
+    consolidation_interval_hours: z
+      .number({
+        error: "memory.substrate.consolidation_interval_hours must be a number",
+      })
+      .int("memory.substrate.consolidation_interval_hours must be an integer")
+      .positive(
+        "memory.substrate.consolidation_interval_hours must be a positive integer",
+      )
+      .optional()
+      .describe(
+        "Hours between scheduled consolidation runs that synthesize buffered memories into concept pages",
+      ),
+    consolidation_max_buffer_lines: z
+      .number({
+        error:
+          "memory.substrate.consolidation_max_buffer_lines must be a number",
+      })
+      .int("memory.substrate.consolidation_max_buffer_lines must be an integer")
+      .positive(
+        "memory.substrate.consolidation_max_buffer_lines must be a positive integer",
+      )
+      .nullable()
+      .optional()
+      .describe(
+        "Size-based trigger for consolidation. When `memory/buffer.md` reaches this many non-empty lines, consolidation runs even if the time-based interval hasn't elapsed. Set to `null` to disable the size trigger and rely solely on `consolidation_interval_hours`.",
+      ),
+    consolidation_max_entries_per_run: z
+      .number({
+        error:
+          "memory.substrate.consolidation_max_entries_per_run must be a number",
+      })
+      .int(
+        "memory.substrate.consolidation_max_entries_per_run must be an integer",
+      )
+      .positive(
+        "memory.substrate.consolidation_max_entries_per_run must be a positive integer",
+      )
+      .nullable()
+      .optional()
+      .describe(
+        "Upper bound on buffer entries one consolidation run may process. When the buffer holds more, the run's cutoff is moved back to the first over-cap entry's timestamp so the overflow is deferred to a follow-up pass. Bounds the context a single agentic run must read after a backlog. Set to `null` to always process the full buffer.",
+      ),
+    max_page_chars: z
+      .number({ error: "memory.substrate.max_page_chars must be a number" })
+      .int("memory.substrate.max_page_chars must be an integer")
+      .positive("memory.substrate.max_page_chars must be a positive integer")
+      .optional()
+      .describe(
+        "Soft upper bound on concept-page body length — pages exceeding this are flagged for split during consolidation",
+      ),
+    consolidation_prompt_path: z
+      .string({
+        error: "memory.substrate.consolidation_prompt_path must be a string",
+      })
+      .nullable()
+      .optional()
+      .describe(
+        "Optional path to a file whose contents replace the bundled consolidation prompt. Relative paths resolve under the workspace root; absolute paths and a leading `~/` (expanded to the home directory) are honored only when they still resolve inside the workspace root — a path that lands outside the workspace (including via symlinks) is rejected. The loaded contents may include `{{CUTOFF}}`, which is substituted with the run's ISO-8601 cutoff timestamp. If the file is rejected, missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
+      ),
+    spread_k: z
+      .number({ error: "memory.substrate.spread_k must be a number" })
+      .min(0, "memory.substrate.spread_k must be >= 0")
+      .max(1, "memory.substrate.spread_k must be <= 1")
+      .optional()
+      .describe(
+        "Spreading-activation propagation coefficient — fraction of own activation that flows to neighbors per hop. Falls back to `memory.v2.k`.",
+      ),
+    spread_hops: z
+      .number({ error: "memory.substrate.spread_hops must be a number" })
+      .int("memory.substrate.spread_hops must be an integer")
+      .nonnegative("memory.substrate.spread_hops must be non-negative")
+      .optional()
+      .describe(
+        "Maximum BFS distance for spreading activation across the concept graph. Falls back to `memory.v2.hops`.",
+      ),
+    ann_candidate_limit: z
+      .number({
+        error: "memory.substrate.ann_candidate_limit must be a number",
+      })
+      .int("memory.substrate.ann_candidate_limit must be an integer")
+      .positive(
+        "memory.substrate.ann_candidate_limit must be a positive integer",
+      )
+      .nullable()
+      .optional()
+      .describe(
+        "Per-channel cap on the unrestricted ANN candidate query used by memory recall (dense and sparse each return up to this many hits before they are unioned). `null` = unlimited (every page in the concept-page collection is eligible).",
+      ),
+  })
+  .describe(
+    "Memory substrate tuning — overrides for the shared concept-page infrastructure (consolidation, hybrid retrieval, BM25 encoding, sweep). Unset keys resolve to their historical `memory.v2` counterparts.",
+  )
+  .superRefine((config, ctx) => {
+    if (
+      config.dense_weight === undefined ||
+      config.sparse_weight === undefined
+    ) {
+      return;
+    }
+    const hybridSum = config.dense_weight + config.sparse_weight;
+    if (Math.abs(hybridSum - 1.0) >= WEIGHT_SUM_TOLERANCE) {
+      const message = `memory.substrate hybrid weights (dense_weight + sparse_weight) must sum to 1.0 (got ${hybridSum.toFixed(4)})`;
+      for (const path of ["dense_weight", "sparse_weight"] as const) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [path],
+          message,
+        });
+      }
+    }
+  });
+
+export type MemorySubstrateConfig = z.infer<typeof MemorySubstrateConfigSchema>;

package/src/config/schemas/memory-v2.ts

@@ -3,9 +3,10 @@ import { z } from "zod";
 /**
  * Tolerance for floating-point comparisons of weight sums. Using 0.001 lets
  * users specify weights to three decimal places without spurious rejections,
- * while still catching obvious mis-sums.
+ * while still catching obvious mis-sums. Shared with the `memory.substrate`
+ * schema so both namespaces apply the same hybrid-weight refinement.
  */
-const WEIGHT_SUM_TOLERANCE = 0.001;
+export const WEIGHT_SUM_TOLERANCE = 0.001;
 
 /**
  * Default cross-encoder model for memory v2 reranking.

package/src/config/schemas/memory-v3.ts

@@ -252,8 +252,7 @@ export const MemoryV3EntitySchema = z
 /**
  * Per-turn injection-gate tuning: thresholds the retrieval signals must clear
  * for the gate to open and run the selector. The gate runs only when the
- * `memory-v3-injection-gate` feature flag (the rollout switch) AND the
- * `enabled` kill-switch below are both on.
+ * `enabled` kill-switch below is on.
  */
 export const MemoryV3GateSchema = z
   .object({
@@ -261,7 +260,7 @@ export const MemoryV3GateSchema = z
       .boolean({ error: "memory.v3.gate.enabled must be a boolean" })
       .default(true)
       .describe(
-        "Whether the injection gate may run at all. false forces the full selection process every turn regardless of the `memory-v3-injection-gate` feature flag; true (default) defers to the flag.",
+        "Whether the injection gate may run at all. false forces the full selection process every turn; true (default) lets the gate run when the thresholds are met.",
       ),
     denseThreshold: z
       .number({ error: "memory.v3.gate.denseThreshold must be a number" })
@@ -327,7 +326,7 @@ export const MemoryV3GateSchema = z
       ),
   })
   .describe(
-    "Memory v3 per-turn injection gate tuning (thresholds; the gate runs when the `memory-v3-injection-gate` feature flag AND `enabled` are both on).",
+    "Memory v3 per-turn injection gate tuning (thresholds; the gate runs when `enabled` is on).",
   );
 
 // NOTE: a retired `workingSet` sub-config (maxPages/evictWindow for the old
@@ -383,6 +382,14 @@ export const MemoryV3ConfigSchema = z
       .describe(
         "Per-lane article budget for the reply-query finder pass: needle and dense each re-run over the assistant's previous message as separate queries (never concatenated with the user's message). 0 disables the pass. Deliberately small next to needleK/denseK — the pass adds the assistant-side retrieval signal, not a second full sweep.",
       ),
+    spanQueryK: z
+      .number({ error: "memory.v3.spanQueryK must be a number" })
+      .int("memory.v3.spanQueryK must be an integer")
+      .nonnegative("memory.v3.spanQueryK must be a non-negative integer")
+      .default(0)
+      .describe(
+        "Per-chunk article budget for the span-query dense pass: the current message's clause spans (merged into at most 8 contiguous chunks) re-run through the dense lane as separate queries, union-additive into the candidate pool. 0 disables the pass; it is also inert when denseK is 0 or the message yields fewer than two chunks. Deliberately small next to denseK — the pass rescues motifs a long message's single query vector averages away, not a second full sweep.",
+      ),
     selectorEnabled: z
       .boolean({ error: "memory.v3.selectorEnabled must be a boolean" })
       .default(true)

package/src/config/schemas/memory.ts

@@ -17,7 +17,8 @@ import {
   MemorySegmentationConfigSchema,
   QdrantConfigSchema,
 } from "./memory-storage.js";
-import { MemoryV2ConfigSchema } from "./memory-v2.js";
+import { MemorySubstrateConfigSchema } from "./memory-substrate.js";
+import { MemoryV2ConfigSchema, WEIGHT_SUM_TOLERANCE } from "./memory-v2.js";
 import { MemoryV3ConfigSchema } from "./memory-v3.js";
 
 export const MemoryConfigSchema = z
@@ -54,6 +55,9 @@ export const MemoryConfigSchema = z
     summarization: MemorySummarizationConfigSchema.default(
       MemorySummarizationConfigSchema.parse({}),
     ),
+    substrate: MemorySubstrateConfigSchema.default(
+      MemorySubstrateConfigSchema.parse({}),
+    ),
     v2: MemoryV2ConfigSchema.default(MemoryV2ConfigSchema.parse({})),
     v3: MemoryV3ConfigSchema.default(MemoryV3ConfigSchema.parse({})),
     retrospective: MemoryRetrospectiveConfigSchema.default(
@@ -118,6 +122,36 @@ export const MemoryConfigSchema = z
           "memory.retrieval.injection.perTurn.capabilityReserve + serendipitySlots must be less than maxNodes",
       });
     }
+    // Resolved hybrid-weight invariant. `resolveSubstrateTuning` pairs each
+    // `memory.substrate` weight with its `memory.v2` twin on an
+    // undefined-only fallback, so a single substrate weight forms its
+    // effective pair with the v2 value (schema default applied by now). The
+    // substrate schema's own refinement already covers the both-set case, and
+    // the v2 schema covers the neither-set case — this check guards the mixed
+    // case those local refinements cannot see.
+    const substrateDense = config.substrate?.dense_weight;
+    const substrateSparse = config.substrate?.sparse_weight;
+    const oneSubstrateWeightSet =
+      (substrateDense === undefined) !== (substrateSparse === undefined);
+    if (oneSubstrateWeightSet) {
+      const effectiveDense =
+        substrateDense !== undefined ? substrateDense : config.v2.dense_weight;
+      const effectiveSparse =
+        substrateSparse !== undefined
+          ? substrateSparse
+          : config.v2.sparse_weight;
+      const effectiveSum = effectiveDense + effectiveSparse;
+      if (Math.abs(effectiveSum - 1.0) >= WEIGHT_SUM_TOLERANCE) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [
+            "substrate",
+            substrateDense !== undefined ? "dense_weight" : "sparse_weight",
+          ],
+          message: `memory hybrid weights must sum to 1.0 after memory.substrate → memory.v2 fallback (effective dense_weight ${effectiveDense.toFixed(4)} + sparse_weight ${effectiveSparse.toFixed(4)} = ${effectiveSum.toFixed(4)})`,
+        });
+      }
+    }
   });
 
 export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;

package/src/config/schemas/services.ts

@@ -20,7 +20,9 @@ export const VALID_INFERENCE_PROVIDERS = [
   "openrouter",
 ] as const;
 
-const VALID_IMAGE_GEN_PROVIDERS = ["gemini", "openai"] as const;
+// `vellum` generates through the platform runtime proxy; the backend
+// (gemini/openai) derives from the selected model's prefix at request time.
+const VALID_IMAGE_GEN_PROVIDERS = ["vellum", "gemini", "openai"] as const;
 
 /**
  * Derived from `SEARCH_PROVIDER_CATALOG`. Adding a new web-search provider
@@ -51,7 +53,13 @@ const BaseServiceSchema = z.object({
  */
 const InferenceServiceSchema = z.object({});
 
-const ImageGenerationServiceSchema = BaseServiceSchema.extend({
+/**
+ * Image generation carries no `mode`: `provider` is the only axis. `"vellum"`
+ * generates through the platform runtime proxy for the model-appropriate
+ * backend, billed to Vellum credits; `"gemini"`/`"openai"` use the user's
+ * key. A `mode` key sent by an older client is stripped at parse.
+ */
+const ImageGenerationServiceSchema = z.object({
   provider: z.enum(VALID_IMAGE_GEN_PROVIDERS).default("gemini"),
   model: z.string().default(DEFAULT_IMAGE_MODEL),
 });

package/src/config/substrate-twin-shadowing.ts

@@ -0,0 +1,195 @@
+// ---------------------------------------------------------------------------
+// Memory substrate — twin-namespace shadowing detection
+// ---------------------------------------------------------------------------
+
+/** One `memory.v2` tunable's `memory.substrate` twin. */
+interface SubstrateTwin {
+  /** The twin's `memory.substrate` key, e.g. `spread_k` for `k`. */
+  readonly substrateKey: string;
+  /**
+   * Whether the v2 injection engine reads the `memory.v2` key straight out of
+   * its own namespace (`v2/injection.ts`, `v2/activation.ts`,
+   * `v2/backfill-jobs.ts`) rather than through `resolveSubstrateTuning`. For
+   * these keys the two namespaces feed two different consumers, so a
+   * `memory.v2` write retunes the v2 engine while substrate recall keeps
+   * reading the substrate twin — the pair can hold different effective values
+   * at once.
+   */
+  readonly alsoReadByV2Engine: boolean;
+}
+
+/**
+ * `memory.v2` key → its `memory.substrate` twin, for the fifteen substrate
+ * tunables that exist in both namespaces. `k` / `hops` are the historical
+ * `memory.v2` names for `spread_k` / `spread_hops`; every other key shares its
+ * name with its twin.
+ *
+ * Substrate precedence lives in `resolveSubstrateTuning`
+ * (`plugins/defaults/memory/substrate/tuning.ts`), which resolves each tunable
+ * as `memory.substrate.X ?? memory.v2.X`. Twelve keys reach the runtime only
+ * through that resolver; the three carrying `alsoReadByV2Engine` are read a
+ * second time by the live v2 injection engine off `config.memory.v2` directly.
+ *
+ * This table is the config surface's view of the same pairing, kept honest by
+ * `__tests__/substrate-twin-shadowing.test.ts`, which asserts it covers exactly
+ * the `memory.substrate` schema's keys.
+ */
+export const SUBSTRATE_TWIN_BY_V2_KEY: Readonly<Record<string, SubstrateTwin>> =
+  {
+    sweep_enabled: { substrateKey: "sweep_enabled", alsoReadByV2Engine: false },
+    dense_weight: { substrateKey: "dense_weight", alsoReadByV2Engine: false },
+    sparse_weight: { substrateKey: "sparse_weight", alsoReadByV2Engine: false },
+    min_sparse_spread: {
+      substrateKey: "min_sparse_spread",
+      alsoReadByV2Engine: false,
+    },
+    full_sparse_spread: {
+      substrateKey: "full_sparse_spread",
+      alsoReadByV2Engine: false,
+    },
+    bm25_k1: { substrateKey: "bm25_k1", alsoReadByV2Engine: false },
+    bm25_b: { substrateKey: "bm25_b", alsoReadByV2Engine: false },
+    consolidation_interval_hours: {
+      substrateKey: "consolidation_interval_hours",
+      alsoReadByV2Engine: false,
+    },
+    consolidation_max_buffer_lines: {
+      substrateKey: "consolidation_max_buffer_lines",
+      alsoReadByV2Engine: false,
+    },
+    consolidation_max_entries_per_run: {
+      substrateKey: "consolidation_max_entries_per_run",
+      alsoReadByV2Engine: false,
+    },
+    max_page_chars: {
+      substrateKey: "max_page_chars",
+      alsoReadByV2Engine: false,
+    },
+    consolidation_prompt_path: {
+      substrateKey: "consolidation_prompt_path",
+      alsoReadByV2Engine: false,
+    },
+    // The v2 injection engine reads these three off `config.memory.v2`:
+    // `k` / `hops` in `v2/injection.ts` and `v2/backfill-jobs.ts`,
+    // `ann_candidate_limit` in `v2/activation.ts`.
+    k: { substrateKey: "spread_k", alsoReadByV2Engine: true },
+    hops: { substrateKey: "spread_hops", alsoReadByV2Engine: true },
+    ann_candidate_limit: {
+      substrateKey: "ann_candidate_limit",
+      alsoReadByV2Engine: true,
+    },
+  };
+
+/** A `memory.substrate` value set on the twin of a given `memory.v2` key. */
+export type SubstrateShadowing = {
+  /** Dotted path of the twin, e.g. `memory.substrate.spread_k`. */
+  substratePath: string;
+  /** The twin's persisted value — what substrate recall resolves to. */
+  substrateValue: unknown;
+  /**
+   * Whether the v2 injection engine also reads the `memory.v2` key directly,
+   * so the write is not inert (see {@link SubstrateTwin.alsoReadByV2Engine}).
+   */
+  alsoReadByV2Engine: boolean;
+};
+
+function readPlainObject(value: unknown): Record<string, unknown> | undefined {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * The `memory.substrate` twin covering `path`, or `undefined` when `path` is
+ * not a shadowable `memory.v2` tunable or its twin is unset.
+ *
+ * `memory.substrate` is override-only and wins for substrate recall whenever
+ * its key is present — including when it holds an explicit `null`, which
+ * `resolveSubstrateTuning` treats as present. Detection therefore keys on
+ * presence, not truthiness. What that means for the `memory.v2` key depends on
+ * `alsoReadByV2Engine`: for a substrate-only twin the `memory.v2` value has no
+ * remaining consumer, while for the three engine-read twins it still tunes v2
+ * injection.
+ *
+ * `raw` is the unparsed config object (`loadRawConfig()` / the `config_get`
+ * payload), so the check sees exactly what is persisted.
+ */
+export function findSubstrateShadowing(
+  raw: Record<string, unknown>,
+  path: string,
+): SubstrateShadowing | undefined {
+  const segments = path.split(".");
+  if (segments.length !== 3 || segments[0] !== "memory") {
+    return undefined;
+  }
+  const [, namespace, key] = segments as [string, string, string];
+  if (namespace !== "v2") {
+    return undefined;
+  }
+  const twin = SUBSTRATE_TWIN_BY_V2_KEY[key];
+  if (twin === undefined) {
+    return undefined;
+  }
+  const substrate = readPlainObject(readPlainObject(raw.memory)?.substrate);
+  if (!substrate || !(twin.substrateKey in substrate)) {
+    return undefined;
+  }
+  return {
+    substratePath: `memory.substrate.${twin.substrateKey}`,
+    substrateValue: substrate[twin.substrateKey],
+    alsoReadByV2Engine: twin.alsoReadByV2Engine,
+  };
+}
+
+/**
+ * Operator-facing warning for a `config set` on a `memory.v2` tunable whose
+ * `memory.substrate` twin is set.
+ *
+ * Two classes, two messages. A substrate-only twin leaves the write with no
+ * consumer, so the warning names the winning key and the command that actually
+ * retunes it. An engine-read twin (`k`, `hops`, `ann_candidate_limit`) makes
+ * the write effective for v2 injection while substrate recall stays on the
+ * twin, so the warning reports the split rather than a no-op.
+ */
+export function describeShadowedConfigSet(
+  shadowing: SubstrateShadowing,
+  path: string,
+): string {
+  const value = JSON.stringify(shadowing.substrateValue) ?? "undefined";
+  if (shadowing.alsoReadByV2Engine) {
+    return (
+      `${path} is read directly by the memory-v2 injection engine, so this write ` +
+      `does change its behavior. Substrate recall reads ${shadowing.substratePath} ` +
+      `(${value}) instead, so the two can diverge. ` +
+      `Run 'assistant config set ${shadowing.substratePath} <value>' to move substrate recall with it.`
+    );
+  }
+  return (
+    `${shadowing.substratePath} is set (${value}) and takes precedence over ${path}, ` +
+    `so this write does not change the effective value. ` +
+    `Run 'assistant config set ${shadowing.substratePath} <value>' to retune it.`
+  );
+}
+
+/**
+ * Operator-facing annotation for a `config get` of a `memory.v2` tunable whose
+ * `memory.substrate` twin is set — the read-side counterpart of
+ * {@link describeShadowedConfigSet}, split along the same two classes so a read
+ * never confirms a value the runtime ignores nor denies one it honors.
+ */
+export function describeShadowedConfigGet(
+  shadowing: SubstrateShadowing,
+  path: string,
+): string {
+  const value = JSON.stringify(shadowing.substrateValue) ?? "undefined";
+  if (shadowing.alsoReadByV2Engine) {
+    return (
+      `Split: ${shadowing.substratePath} = ${value} is the effective value for ` +
+      `substrate recall, while the memory-v2 injection engine reads ${path} above.`
+    );
+  }
+  return (
+    `Shadowed: ${shadowing.substratePath} = ${value} takes precedence and is ` +
+    `the effective value.`
+  );
+}

package/src/config/webhook-routing.ts

@@ -0,0 +1,67 @@
+/**
+ * Derivations answering "is this deployment set up to receive provider
+ * webhooks?" from workspace config.
+ *
+ * Two consumers ask the same question for different reasons: the channel
+ * readiness probes report it to the user, and the Telegram webhook health
+ * sweep uses it to decide whether a missing/broken registration is even
+ * meaningful. Both must agree — a probe that says "ingress is configured"
+ * while the sweep says "no webhook expected" would be a silent divergence.
+ */
+
+import {
+  normalizePublicBaseUrl,
+  resolveTwilioPublicBaseUrl,
+} from "@vellumai/service-contracts/twilio-ingress";
+
+import { getIsPlatform } from "./env-registry.js";
+import { loadRawConfig } from "./loader.js";
+
+/**
+ * True when a public ingress base URL is set and ingress is enabled.
+ *
+ * `ingress.enabled` is treated as opt-out: an unset flag with a base URL
+ * present counts as enabled, matching how the URL alone has always been
+ * enough to drive registration.
+ */
+export function hasIngressConfigured(
+  options: { twilio?: boolean } = {},
+): boolean {
+  try {
+    const raw = loadRawConfig();
+    const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
+    const effectiveBaseUrl = options.twilio
+      ? (resolveTwilioPublicBaseUrl(ingress) ?? "")
+      : (normalizePublicBaseUrl(ingress.publicBaseUrl) ?? "");
+    const enabled =
+      (ingress.enabled as boolean | undefined) ??
+      (effectiveBaseUrl ? true : false);
+    return enabled && effectiveBaseUrl.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when inbound webhooks have somewhere to land: either a self-hosted
+ * public ingress URL, or — when `allowManagedCallbacks` is set and this is a
+ * platform deployment — the platform's managed callback routes.
+ */
+export function hasWebhookRoutingConfigured(
+  allowManagedCallbacks = false,
+  options: { twilio?: boolean } = {},
+): {
+  configured: boolean;
+  usesManagedCallbacks: boolean;
+} {
+  const ingressConfigured = hasIngressConfigured(options);
+  if (ingressConfigured) {
+    return { configured: true, usesManagedCallbacks: false };
+  }
+
+  const usesManagedCallbacks = allowManagedCallbacks && getIsPlatform();
+  return {
+    configured: usesManagedCallbacks,
+    usesManagedCallbacks,
+  };
+}

package/src/context/compactor.ts

@@ -1050,9 +1050,13 @@ function truncateHistoryToBudget(args: {
   systemPrompt: string;
   budgetTokens: number;
   providerName: string;
+  model?: string;
 }): Message[] {
-  const { messages, systemPrompt, budgetTokens, providerName } = args;
-  let estimate = estimatePromptTokens(messages, systemPrompt, { providerName });
+  const { messages, systemPrompt, budgetTokens, providerName, model } = args;
+  let estimate = estimatePromptTokens(messages, systemPrompt, {
+    providerName,
+    model,
+  });
   if (estimate <= budgetTokens || messages.length <= 1) {
     return messages;
   }
@@ -1061,6 +1065,7 @@ function truncateHistoryToBudget(args: {
     dropCount++;
     estimate = estimatePromptTokens(messages.slice(dropCount), systemPrompt, {
       providerName,
+      model,
     });
   }
   if (dropCount === 0) {
@@ -1155,6 +1160,7 @@ export async function runAssistantDrivenCompaction(
     systemPrompt: args.systemPrompt,
     budgetTokens: compactionPrefixBudget(args.maxInputTokens),
     providerName: args.provider.tokenEstimationProvider ?? args.provider.name,
+    model: args.provider.defaultModel,
   });
   const requestMessages = buildCompactionRequest(summaryHistory, instruction);
 
@@ -1354,7 +1360,7 @@ export async function runAssistantDrivenCompaction(
       estimatePromptTokens(
         [...fixedPrefix, ...stripInjectionsForCompaction(tail)],
         args.systemPrompt,
-        { providerName, toolTokenBudget },
+        { providerName, model: args.provider.defaultModel, toolTokenBudget },
       );
     const floorIndex = resolveTailFloorIndex(args.messages, pairedTailIndex);
     const advanced = advanceTailForBudget({
@@ -1616,6 +1622,7 @@ export async function runEmergencyCompaction(
     systemPrompt: args.systemPrompt,
     budgetTokens: compactionPrefixBudget(args.maxInputTokens),
     providerName: args.provider.tokenEstimationProvider ?? args.provider.name,
+    model: args.provider.defaultModel,
   });
 
   const instruction: Message = {

package/src/context/token-estimator.ts

@@ -3,6 +3,11 @@ import {
   normalizeGeminiAudioMime,
 } from "../providers/gemini/inline-media.js";
 import { mediaSourceByteLength } from "../providers/media-resolve.js";
+import { modelSupportsAudioInput } from "../providers/model-catalog.js";
+import {
+  estimateOpenAICompatAudioTokens,
+  isOpenAICompatInlineAudio,
+} from "../providers/openai/input-audio.js";
 import type {
   ContentBlock,
   Message,
@@ -90,6 +95,12 @@ const TOOL_DEFINITION_OVERHEAD_TOKENS = 28;
 
 export interface TokenEstimatorOptions {
   providerName?: string;
+  /**
+   * Model id the estimated request dispatches to, for model-keyed rules
+   * (e.g. audio-capable OpenAI-compatible models). Callers pass the
+   * provider's `defaultModel` when available.
+   */
+  model?: string;
   /** Pre-computed tool token budget. When provided, added to the prompt total. */
   toolTokenBudget?: number;
 }
@@ -142,6 +153,16 @@ function estimateFileDataTokens(
     return Math.ceil((Math.ceil(byteLength / 3) * 4) / CHARS_PER_TOKEN);
   }
 
+  // Audio-native OpenAI-compatible models (catalog `supportsAudioInput`)
+  // receive eligible audio inline as `input_audio` parts, billed by duration.
+  if (
+    options?.model !== undefined &&
+    modelSupportsAudioInput(options.model) &&
+    isOpenAICompatInlineAudio(block.source.media_type, byteLength)
+  ) {
+    return estimateOpenAICompatAudioTokens(byteLength);
+  }
+
   return 0;
 }