@vellumai/assistant 0.7.1 → 0.7.3

package/src/config/schemas/heartbeat.ts

@@ -1,3 +1,4 @@
+import { Cron } from "croner";
 import { z } from "zod";
 
 export const HeartbeatConfigSchema = z
@@ -10,8 +11,22 @@ export const HeartbeatConfigSchema = z
       .number({ error: "heartbeat.intervalMs must be a number" })
       .int("heartbeat.intervalMs must be an integer")
       .positive("heartbeat.intervalMs must be a positive integer")
-      .default(6 * 3_600_000)
+      .default(30 * 60_000)
       .describe("Time between heartbeat checks in milliseconds"),
+    cronExpression: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe(
+        "Cron expression for heartbeat timing. When set, heartbeats fire at the specified clock times instead of using intervalMs.",
+      ),
+    timezone: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe(
+        "Timezone for cron expression evaluation, e.g. 'America/New_York'. Ignored when cronExpression is null.",
+      ),
     activeHoursStart: z
       .number({ error: "heartbeat.activeHoursStart must be a number" })
       .int("heartbeat.activeHoursStart must be an integer")
@@ -80,6 +95,54 @@ export const HeartbeatConfigSchema = z
         message,
       });
     }
+
+    // Validate cronExpression and timezone when cronExpression is set.
+    // Separate the validations so timezone errors are attributed to the
+    // timezone path — if both paths point at cronExpression, the config
+    // loader's delete-and-retry would strip cronExpression but leave the
+    // invalid timezone, cascading to a full defaults reset.
+    if (config.cronExpression != null) {
+      try {
+        new Cron(config.cronExpression, { maxRuns: 0 });
+      } catch (err) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["cronExpression"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      if (config.timezone != null) {
+        try {
+          new Cron(config.cronExpression, {
+            maxRuns: 0,
+            timezone: config.timezone,
+          });
+        } catch {
+          // The cron expression itself is valid (or already flagged above),
+          // so a failure here is from the timezone.
+          try {
+            Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+          } catch (tzErr) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ["timezone"],
+              message: tzErr instanceof Error ? tzErr.message : String(tzErr),
+            });
+          }
+        }
+      }
+    } else if (config.timezone != null) {
+      // cronExpression is null but timezone is set — validate timezone independently
+      try {
+        Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+      } catch (err) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["timezone"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
   });
 
 export type HeartbeatConfig = z.infer<typeof HeartbeatConfigSchema>;

package/src/config/schemas/ingress.ts

@@ -1,5 +1,14 @@
 import { z } from "zod";
 
+function emptyOrAbsoluteHttpUrl(fieldPath: string) {
+  return z
+    .string({ error: `${fieldPath} must be a string` })
+    .refine(
+      (val) => val === "" || /^https?:\/\//i.test(val),
+      `${fieldPath} must be an absolute URL starting with http:// or https://`,
+    );
+}
+
 const IngressWebhookConfigSchema = z
   .object({
     secret: z
@@ -74,12 +83,7 @@ const IngressBaseSchema = z
       .boolean({ error: "ingress.enabled must be a boolean" })
       .optional()
       .describe("Whether the ingress HTTP server is enabled"),
-    publicBaseUrl: z
-      .string({ error: "ingress.publicBaseUrl must be a string" })
-      .refine(
-        (val) => val === "" || /^https?:\/\//i.test(val),
-        "ingress.publicBaseUrl must be an absolute URL starting with http:// or https://",
-      )
+    publicBaseUrl: emptyOrAbsoluteHttpUrl("ingress.publicBaseUrl")
       .default("")
       .describe(
         "Public-facing base URL for the ingress server (used in webhook callbacks)",

package/src/config/schemas/llm.ts

@@ -70,6 +70,8 @@ export const LLMCallSiteEnum = z.enum([
   "inference",
   "feedEventCopy",
   "trustRuleSuggestion",
+  "proactiveArtifactDecision",
+  "proactiveArtifactBuild",
 ]);
 export type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
 
@@ -91,7 +93,6 @@ export type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
  * mapping table.
  */
 const EffortEnum = z.enum(["none", "low", "medium", "high", "xhigh", "max"]);
-export type Effort = z.infer<typeof EffortEnum>;
 
 export const SpeedEnum = z.enum(["standard", "fast"]);
 export type Speed = z.infer<typeof SpeedEnum>;
@@ -102,7 +103,6 @@ export type Speed = z.infer<typeof SpeedEnum>;
  * are stripped in `retry.ts` normalization.
  */
 const VerbosityEnum = z.enum(["low", "medium", "high"]);
-export type Verbosity = z.infer<typeof VerbosityEnum>;
 
 // ---------------------------------------------------------------------------
 // Leaf primitives (shared between LLMConfigBase and LLMConfigFragment)
@@ -150,7 +150,6 @@ const ThinkingSchema = z.object({
   enabled: ThinkingEnabledSchema.default(true),
   streamThinking: ThinkingStreamThinkingSchema.default(true),
 });
-export type Thinking = z.infer<typeof ThinkingSchema>;
 
 // Fragment view: every field optional, no defaults injected. Defining this
 // separately (rather than `ThinkingSchema.partial()`) avoids having Zod
@@ -243,7 +242,6 @@ const OpenRouterOnlyItemSchema = z.string().min(1);
 const OpenRouterSchema = z.object({
   only: z.array(OpenRouterOnlyItemSchema).default([]),
 });
-export type OpenRouter = z.infer<typeof OpenRouterSchema>;
 
 const OpenRouterDeepPartialSchema = z.object({
   only: z.array(OpenRouterOnlyItemSchema).optional(),
@@ -257,8 +255,8 @@ const OpenRouterDeepPartialSchema = z.object({
  * Distinguishes daemon-managed profiles (overwritten on every startup) from
  * user-created ones (never touched by the daemon).
  */
-export const ProfileSource = z.enum(["managed", "user"]);
-export type ProfileSource = z.infer<typeof ProfileSource>;
+const ProfileSource = z.enum(["managed", "user"]);
+type ProfileSource = z.infer<typeof ProfileSource>;
 
 // ---------------------------------------------------------------------------
 // Pricing overrides
@@ -270,7 +268,6 @@ const PricingOverrideSchema = z.object({
   inputPer1M: z.number().nonnegative(),
   outputPer1M: z.number().nonnegative(),
 });
-export type PricingOverride = z.infer<typeof PricingOverrideSchema>;
 
 // ---------------------------------------------------------------------------
 // Base config (all fields defaulted) and Fragment (all fields optional)
@@ -302,7 +299,7 @@ export type LLMConfigBase = z.infer<typeof LLMConfigBase>;
  * objects so callers can override individual leaves (e.g. `{ thinking:
  * { enabled: false } }`).
  */
-export const LLMConfigFragment = z.object({
+const LLMConfigFragment = z.object({
   provider: LLMProvider.optional(),
   model: ModelSchema.optional(),
   maxTokens: MaxTokensSchema.optional(),
@@ -314,7 +311,7 @@ export const LLMConfigFragment = z.object({
   contextWindow: ContextWindowDeepPartialSchema.optional(),
   openrouter: OpenRouterDeepPartialSchema.optional(),
 });
-export type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
+type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
 
 /**
  * A named profile entry: an `LLMConfigFragment` augmented with
@@ -337,7 +334,7 @@ export type ProfileEntry = z.infer<typeof ProfileEntry>;
 const LLMCallSiteConfig = LLMConfigFragment.extend({
   profile: z.string().min(1).optional(),
 });
-export type LLMCallSiteConfig = z.infer<typeof LLMCallSiteConfig>;
+type LLMCallSiteConfig = z.infer<typeof LLMCallSiteConfig>;
 
 // ---------------------------------------------------------------------------
 // Top-level LLM schema

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

@@ -1,29 +1,82 @@
 import { z } from "zod";
 
-export const MemoryJobsConfigSchema = z
-  .object({
-    workerConcurrency: z
-      .number({ error: "memory.jobs.workerConcurrency must be a number" })
-      .int("memory.jobs.workerConcurrency must be an integer")
-      .positive("memory.jobs.workerConcurrency must be a positive integer")
-      .default(2)
-      .describe("Number of concurrent workers processing memory jobs"),
-    batchSize: z
-      .number({ error: "memory.jobs.batchSize must be a number" })
-      .int("memory.jobs.batchSize must be an integer")
-      .positive("memory.jobs.batchSize must be a positive integer")
-      .default(10)
-      .describe("Number of memory items processed per batch"),
-    stalledJobTimeoutMs: z
-      .number({ error: "memory.jobs.stalledJobTimeoutMs must be a number" })
-      .int("memory.jobs.stalledJobTimeoutMs must be an integer")
-      .positive("memory.jobs.stalledJobTimeoutMs must be a positive integer")
-      .default(30 * 60 * 1000)
-      .describe(
-        "Timeout in milliseconds after which a stalled memory job is considered failed",
-      ),
-  })
-  .describe("Memory background job processing configuration");
+const DEFAULT_WORKER_CONCURRENCY = 2;
+const DEFAULT_SLOW_LLM_CONCURRENCY = 1;
+const DEFAULT_FAST_CONCURRENCY = 2;
+const DEFAULT_EMBED_CONCURRENCY = 2;
+
+const positiveInt = (field: string) =>
+  z
+    .number({ error: `memory.jobs.${field} must be a number` })
+    .int(`memory.jobs.${field} must be an integer`)
+    .positive(`memory.jobs.${field} must be a positive integer`);
+
+// Input shape allows all fields to be omitted so we can distinguish
+// "user explicitly set workerConcurrency" from "user accepted the default"
+// when deriving lane caps. The output shape (after transform) always has
+// all four fields populated.
+const MemoryJobsConfigInputSchema = z.object({
+  workerConcurrency: positiveInt("workerConcurrency")
+    .optional()
+    .describe("Number of concurrent workers processing memory jobs"),
+  stalledJobTimeoutMs: positiveInt("stalledJobTimeoutMs")
+    .default(30 * 60 * 1000)
+    .describe(
+      "Timeout in milliseconds after which a stalled memory job is considered failed",
+    ),
+  slowLlmConcurrency: positiveInt("slowLlmConcurrency")
+    .optional()
+    .describe(
+      "Concurrent slow LLM-bound jobs (graph consolidation, narrative refine, etc.)",
+    ),
+  fastConcurrency: positiveInt("fastConcurrency")
+    .optional()
+    .describe(
+      "Concurrent fast jobs (concept-page embed, prunes, media processing, etc.)",
+    ),
+  embedConcurrency: positiveInt("embedConcurrency")
+    .optional()
+    .describe(
+      "Concurrent segment-embed jobs (gated by Qdrant circuit breaker)",
+    ),
+});
+
+export const MemoryJobsConfigSchema = MemoryJobsConfigInputSchema.transform(
+  (input) => {
+    // When `workerConcurrency` is explicitly set but lane caps are not,
+    // derive lane caps so existing user configs gain the per-lane fix
+    // without edits. Explicit lane caps always win.
+    const workerConcurrencyExplicit = input.workerConcurrency !== undefined;
+    const workerConcurrency =
+      input.workerConcurrency ?? DEFAULT_WORKER_CONCURRENCY;
+
+    const slowLlmConcurrency =
+      input.slowLlmConcurrency ??
+      (workerConcurrencyExplicit
+        ? Math.max(1, Math.floor(workerConcurrency / 2))
+        : DEFAULT_SLOW_LLM_CONCURRENCY);
+
+    const fastConcurrency =
+      input.fastConcurrency ??
+      (workerConcurrencyExplicit
+        ? workerConcurrency
+        : DEFAULT_FAST_CONCURRENCY);
+
+    const embedConcurrency =
+      input.embedConcurrency ??
+      (workerConcurrencyExplicit
+        ? workerConcurrency
+        : DEFAULT_EMBED_CONCURRENCY);
+
+    return {
+      workerConcurrency,
+      stalledJobTimeoutMs: input.stalledJobTimeoutMs,
+      slowLlmConcurrency,
+      fastConcurrency,
+      embedConcurrency,
+    };
+  },
+).describe("Memory background job processing configuration");
 
 export const MemoryRetentionConfigSchema = z
   .object({
@@ -96,6 +149,19 @@ export const MemoryCleanupConfigSchema = z
       .describe(
         "Retention period for LLM request/response logs in milliseconds (null keeps forever, 0 prunes immediately)",
       ),
+    traceEventRetentionDays: z
+      .number({
+        error: "memory.cleanup.traceEventRetentionDays must be a number",
+      })
+      .int("memory.cleanup.traceEventRetentionDays must be an integer")
+      .nonnegative(
+        "memory.cleanup.traceEventRetentionDays must be non-negative",
+      )
+      .max(365, "memory.cleanup.traceEventRetentionDays must be <= 365 days")
+      .default(3)
+      .describe(
+        "Number of days to retain trace events before cleanup (0 disables pruning)",
+      ),
   })
   .describe("Automatic memory cleanup and garbage collection settings");
 

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

@@ -7,6 +7,33 @@ import { z } from "zod";
  */
 const WEIGHT_SUM_TOLERANCE = 0.001;
 
+/**
+ * Default cross-encoder model for memory v2 reranking.
+ * `Alibaba-NLP/gte-reranker-modernbert-base` (149M, Apache-2.0) — 2025
+ * ModernBERT-backbone reranker; smaller, newer, and cleaner-licensed than
+ * the bge family while matching or beating their retrieval-benchmark scores.
+ * Has ONNX exports at the standard `onnx/model.onnx` path.
+ */
+const DEFAULT_RERANK_MODEL = "Alibaba-NLP/gte-reranker-modernbert-base";
+
+/**
+ * ONNX weight precision passed to `@huggingface/transformers`. Sourced from
+ * transformers.js's supported `dtype` values; `q8` (int8) is ~3× faster than
+ * `fp32` on CPU with negligible reranker accuracy loss. Single source of
+ * truth for both the schema enum and the `LocalRerankBackend` type.
+ */
+export const RerankDtypeEnum = z.enum([
+  "fp32",
+  "fp16",
+  "q8",
+  "int8",
+  "uint8",
+  "q4",
+  "bnb4",
+  "q4f16",
+]);
+export type RerankDtype = z.infer<typeof RerankDtypeEnum>;
+
 /**
  * Memory v2 (concept-page activation model) configuration.
  *
@@ -21,7 +48,7 @@ export const MemoryV2ConfigSchema = z
   .object({
     enabled: z
       .boolean({ error: "memory.v2.enabled must be a boolean" })
-      .default(false)
+      .default(true)
       .describe(
         "Whether the v2 memory subsystem (concept-page activation model) is enabled. Independent of the memory-v2-enabled feature flag — both must be true for v2 to run.",
       ),
@@ -83,17 +110,18 @@ export const MemoryV2ConfigSchema = z
       .number({ error: "memory.v2.top_k must be a number" })
       .int("memory.v2.top_k must be an integer")
       .positive("memory.v2.top_k must be a positive integer")
-      .default(20)
+      .default(25)
       .describe(
-        "Number of top-activation concept pages considered for injection per turn",
+        "Number of top-activation entries (concept pages and skills combined) considered for injection per turn. Skills are scored alongside concepts in the same pool; this cap covers both.",
       ),
-    top_k_skills: z
-      .number({ error: "memory.v2.top_k_skills must be a number" })
-      .int()
-      .nonnegative()
-      .default(5)
+    ann_candidate_limit: z
+      .number({ error: "memory.v2.ann_candidate_limit must be a number" })
+      .int("memory.v2.ann_candidate_limit must be an integer")
+      .positive("memory.v2.ann_candidate_limit must be a positive integer")
+      .nullable()
+      .default(null)
       .describe(
-        "Cap on the per-turn skill-autoinjection slate rendered in `### Skills You Can Use`. 0 disables skill autoinjection without code changes.",
+        "Per-channel cap on the unrestricted ANN candidate query (dense and sparse each return up to this many hits before they are unioned and fed into the activation pipeline). `null` = unlimited (every page in the v2 collection is eligible). Increase or null this out to surface more candidates at the cost of higher per-turn embedding/scoring work.",
       ),
     epsilon: z
       .number({ error: "memory.v2.epsilon must be a number" })
@@ -107,17 +135,52 @@ export const MemoryV2ConfigSchema = z
       .number({ error: "memory.v2.dense_weight must be a number" })
       .min(0, "memory.v2.dense_weight must be >= 0")
       .max(1, "memory.v2.dense_weight must be <= 1")
-      .default(0.7)
+      .default(0.85)
       .describe(
-        "Weight on dense (cosine) similarity in the hybrid retrieval score",
+        "Weight on dense (cosine) similarity in the hybrid retrieval score — dense embeddings dominate the score.",
       ),
     sparse_weight: z
       .number({ error: "memory.v2.sparse_weight must be a number" })
       .min(0, "memory.v2.sparse_weight must be >= 0")
       .max(1, "memory.v2.sparse_weight must be <= 1")
-      .default(0.3)
+      .default(0.15)
+      .describe(
+        "Weight on sparse (BM25-style) similarity in the hybrid retrieval score — sparse acts as a discriminator for keyword-rich queries.",
+      ),
+    // Adaptive sparse-weighting knobs. Both fields are intentionally
+    // optional with no default — the schema serialiser drops absent
+    // optionals so these stay invisible to operators who never tune them.
+    // The defaults live in `effectiveWeights` (sim.ts).
+    min_sparse_spread: z
+      .number({ error: "memory.v2.min_sparse_spread must be a number" })
+      .min(0, "memory.v2.min_sparse_spread must be >= 0")
+      .max(1, "memory.v2.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.v2.full_sparse_spread must be a number" })
+      .min(0, "memory.v2.full_sparse_spread must be >= 0")
+      .max(1, "memory.v2.full_sparse_spread must be <= 1")
+      .optional()
       .describe(
-        "Weight on sparse (BM25-style) similarity in the hybrid retrieval score",
+        "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.v2.bm25_k1 must be a number" })
+      .min(0, "memory.v2.bm25_k1 must be >= 0")
+      .default(1.2)
+      .describe(
+        "BM25 term-frequency saturation parameter. Standard Lucene default — increase to make repeated mentions of a term matter more, decrease to flatten the curve.",
+      ),
+    bm25_b: z
+      .number({ error: "memory.v2.bm25_b must be a number" })
+      .min(0, "memory.v2.bm25_b must be >= 0")
+      .max(1, "memory.v2.bm25_b must be <= 1")
+      .default(0.4)
+      .describe(
+        "BM25 document-length normalization. 0 disables length normalization, 1 fully normalizes. Lucene's default is 0.75 (tuned for narrative/web corpora); we run lower because concept-page collections include structured list pages with high information density per word — full Lucene normalization over-penalizes them.",
       ),
     consolidation_interval_hours: z
       .number({
@@ -148,6 +211,51 @@ export const MemoryV2ConfigSchema = z
       .describe(
         "Optional path to a file whose contents replace the bundled consolidation prompt. Absolute paths are used as-is, a leading `~/` is expanded to the home directory, otherwise the path is resolved under the workspace root. The loaded contents may include `{{CUTOFF}}`, which is substituted with the run's ISO-8601 cutoff timestamp. If the file is missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
       ),
+    rerank: z
+      .object({
+        enabled: z
+          .boolean()
+          .default(false)
+          .describe(
+            "Whether to apply cross-encoder reranking as an additive A_o boost on the user + assistant channels. Disabled by default — opt in once measured.",
+          ),
+        top_k: z
+          .number()
+          .int()
+          .positive()
+          .max(200)
+          .default(50)
+          .describe(
+            "Number of candidates from the top of the pre-rerank-A_o pool to send through the reranker. Tail candidates contribute zero rerank boost and keep their pure fused activation.",
+          ),
+        alpha: z
+          .number()
+          .min(0)
+          .max(1)
+          .default(0.3)
+          .describe(
+            "Per-channel rerank weight: each top-K slug gets `alpha · normalized_rerank` added to A_o weighted by `c_user` (user channel) or `c_assistant` (assistant channel). Top reranker hit can lift A_o by up to `(c_user + c_assistant) · alpha`; bottom of top_k stays roughly unchanged.",
+          ),
+        model: z
+          .string()
+          .default(DEFAULT_RERANK_MODEL)
+          .describe(
+            "HuggingFace model id for the cross-encoder. Must have an ONNX export reachable from huggingface.co/<model>/resolve/main/onnx/model.onnx.",
+          ),
+        dtype: RerankDtypeEnum.default("q8").describe(
+          "ONNX weight precision passed to `@huggingface/transformers`. `q8` (int8) is ~3× faster than `fp32` on CPU with negligible reranker accuracy loss. The worker fails to spawn if the configured model has no matching quantized export — `reranker.ts` then falls back to pure fused scores for the turn.",
+        ),
+      })
+      .default({
+        enabled: false,
+        top_k: 50,
+        alpha: 0.3,
+        model: DEFAULT_RERANK_MODEL,
+        dtype: "q8",
+      })
+      .describe(
+        "Cross-encoder rerank configuration. When enabled, picks the top-K candidates by pre-rerank A_o, runs the cross-encoder once per channel (user, assistant) on that unified set, and adds an alpha-weighted normalized boost to A_o for each scored slug.",
+      ),
   })
   .describe(
     "Memory v2 — concept-page activation model with hourly LLM-driven consolidation",

package/src/config/schemas/platform.ts

@@ -1,5 +1,41 @@
 import { z } from "zod";
 
+const IANA_TIMEZONE_IDENTIFIER_RE =
+  /^(?:UTC|[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)+)$/;
+
+function canonicalizeIanaTimezone(timezone: string): string | null {
+  const trimmed = timezone.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+  if (!IANA_TIMEZONE_IDENTIFIER_RE.test(trimmed)) {
+    return null;
+  }
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: trimmed,
+    }).resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+}
+
+function timezoneConfigField(path: string) {
+  return z
+    .string({ error: `${path} must be a string` })
+    .transform((value, ctx) => {
+      const canonical = canonicalizeIanaTimezone(value);
+      if (canonical === null) {
+        ctx.addIssue({
+          code: "custom",
+          message: `${path} must be a valid IANA timezone identifier or an empty string`,
+        });
+        return z.NEVER;
+      }
+      return canonical;
+    });
+}
+
 export const PlatformConfigSchema = z
   .object({
     baseUrl: z
@@ -10,6 +46,12 @@ export const PlatformConfigSchema = z
       )
       .default("")
       .describe("Base URL of the Vellum platform API"),
+    subdomain: z
+      .string({ error: "platform.subdomain must be a string" })
+      .default("")
+      .describe(
+        "Registered subdomain on vellum.me (e.g. 'apollobot' → apollobot.vellum.me). Set automatically by 'assistant domain register'.",
+      ),
   })
   .describe("Vellum platform connection settings");
 
@@ -50,11 +92,15 @@ export const DaemonConfigSchema = z
 
 export const UiConfigSchema = z
   .object({
-    userTimezone: z
-      .string({ error: "ui.userTimezone must be a string" })
+    userTimezone: timezoneConfigField("ui.userTimezone")
+      .optional()
+      .describe(
+        "Manual IANA timezone override used for assistant temporal grounding and date/time display (e.g. 'America/New_York'). Use an empty string to clear the setting.",
+      ),
+    detectedTimezone: timezoneConfigField("ui.detectedTimezone")
       .optional()
       .describe(
-        "IANA timezone identifier for displaying dates and times (e.g. 'America/New_York')",
+        "IANA timezone identifier detected from the client environment for assistant temporal grounding when no manual override is configured (e.g. 'America/New_York'). Use an empty string to clear the setting.",
       ),
   })
   .describe(