@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/runtime/routes/conversation-list-routes.ts

@@ -1,10 +1,11 @@
 /**
  * Route handlers for conversation listing, detail, and seen/unread state.
  *
- * GET    /v1/conversations          — paginated conversation list
- * POST   /v1/conversations/seen     — record a seen signal
- * POST   /v1/conversations/unread   — mark a conversation unread
- * GET    /v1/conversations/:id      — conversation detail
+ * GET    /v1/conversations              — paginated conversation list
+ * POST   /v1/conversations/seen         — record a seen signal (single)
+ * POST   /v1/conversations/seen/bulk    — record seen signals (batch)
+ * POST   /v1/conversations/unread       — mark a conversation unread
+ * GET    /v1/conversations/:id          — conversation detail
  */
 
 import { z } from "zod";
@@ -37,7 +38,10 @@ import {
   buildConversationDetailResponse,
   serializeConversationSummary,
 } from "../services/conversation-serializer.js";
-import { publishConversationListAndMetadataChanged } from "../sync/resource-sync-events.js";
+import {
+  publishConversationListAndMetadataChanged,
+  publishConversationListChanged,
+} from "../sync/resource-sync-events.js";
 import {
   BadRequestError,
   InternalError,
@@ -73,6 +77,7 @@ const assistantAttentionSchema = z.object({
       "macos_notification_view",
       "macos_conversation_opened",
       "ios_conversation_opened",
+      "web_bulk_mark_read",
       "telegram_inbound_message",
       "telegram_callback",
       "slack_inbound_message",
@@ -318,6 +323,55 @@ function handleRecordSeen({ body = {}, headers }: RouteHandlerArgs) {
   }
 }
 
+function handleRecordSeenBulk({ body = {}, headers }: RouteHandlerArgs) {
+  const rawIds = body.conversationIds as string[] | undefined;
+  if (!Array.isArray(rawIds) || rawIds.length === 0) {
+    throw new BadRequestError("conversationIds must be a non-empty array");
+  }
+
+  const originClientId = headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const changedIds: string[] = [];
+
+  for (const rawId of rawIds) {
+    try {
+      const conversationId = resolveOrThrow(rawId);
+      const priorState = getAttentionStateByConversationIds([
+        conversationId,
+      ]).get(conversationId);
+      const wasUnseen =
+        priorState != null &&
+        priorState.latestAssistantMessageAt != null &&
+        (priorState.lastSeenAssistantMessageAt == null ||
+          priorState.lastSeenAssistantMessageAt <
+            priorState.latestAssistantMessageAt);
+
+      recordConversationSeenSignal({
+        conversationId,
+        sourceChannel: "vellum",
+        signalType: "web_bulk_mark_read",
+        confidence: "explicit",
+        source: "http-api",
+      });
+
+      if (wasUnseen) {
+        changedIds.push(conversationId);
+      }
+    } catch (err) {
+      log.error(
+        { err, conversationId: rawId },
+        "POST /v1/conversations/seen/bulk: failed for conversation",
+      );
+      // Best-effort: continue with remaining conversations.
+    }
+  }
+
+  if (changedIds.length > 0) {
+    publishConversationListChanged("seen_changed", originClientId);
+  }
+
+  return { ok: true, updated: changedIds.length };
+}
+
 function handleMarkUnread({ body = {}, headers }: RouteHandlerArgs) {
   const rawConversationId = body.conversationId as string | undefined;
   if (!rawConversationId) {
@@ -426,6 +480,24 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({ ok: z.boolean() }),
     handler: handleRecordSeen,
   },
+  {
+    operationId: "recordConversationSeenBulk",
+    endpoint: "conversations/seen/bulk",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Bulk mark conversations as seen",
+    description:
+      "Mark multiple conversations as seen in one request. Emits a single sync invalidation for the entire batch instead of per-conversation events.",
+    tags: ["conversations"],
+    requestBody: z.object({
+      conversationIds: z.array(z.string()).min(1),
+    }),
+    responseBody: z.object({ ok: z.boolean(), updated: z.number() }),
+    handler: handleRecordSeenBulk,
+  },
   {
     operationId: "markConversationUnread",
     endpoint: "conversations/unread",

package/src/runtime/routes/conversation-management-routes.ts

@@ -11,6 +11,7 @@
  * DELETE /v1/conversations/:id            — delete a single conversation
  * POST   /v1/conversations/:id/archive    — archive a conversation
  * POST   /v1/conversations/:id/unarchive  — restore an archived conversation
+ * POST   /v1/conversations/archive/bulk   — archive multiple conversations
  * POST   /v1/conversations/:id/surface    — promote to / demote from Recents
  * POST   /v1/conversations/:id/cancel     — cancel generation
  * POST   /v1/conversations/:id/undo       — undo last message
@@ -362,6 +363,41 @@ function handleUnarchiveConversation({
   return { ok: true, conversationId: resolvedId };
 }
 
+function handleArchiveConversationsBulk({
+  body = {},
+  headers,
+}: RouteHandlerArgs) {
+  const rawIds = body.conversationIds as string[] | undefined;
+  if (!Array.isArray(rawIds) || rawIds.length === 0) {
+    throw new BadRequestError("conversationIds must be a non-empty array");
+  }
+
+  const originClientId = headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const archivedIds: string[] = [];
+
+  for (const rawId of rawIds) {
+    try {
+      const conversationId = resolveOrThrow(rawId);
+      const archived = archiveConversation(conversationId);
+      if (archived) {
+        archivedIds.push(conversationId);
+      }
+    } catch (err) {
+      log.error(
+        { err, conversationId: rawId },
+        "POST /v1/conversations/archive/bulk: failed for conversation",
+      );
+      // Best-effort: continue with remaining conversations.
+    }
+  }
+
+  if (archivedIds.length > 0) {
+    publishConversationListChanged("reordered", originClientId);
+  }
+
+  return { ok: true, archived: archivedIds.length };
+}
+
 /**
  * Set or clear the `surfacedAt` promotion marker on a conversation.
  *
@@ -695,6 +731,24 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleUnarchiveConversation,
   },
+  {
+    operationId: "archiveConversationsBulk",
+    endpoint: "conversations/archive/bulk",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Bulk archive conversations",
+    description:
+      "Archive multiple conversations in one request. Emits a single sync invalidation for the entire batch.",
+    tags: ["conversations"],
+    requestBody: z.object({
+      conversationIds: z.array(z.string()).min(1),
+    }),
+    responseBody: z.object({ ok: z.boolean(), archived: z.number() }),
+    handler: handleArchiveConversationsBulk,
+  },
   {
     operationId: "surfaceConversation",
     endpoint: "conversations/:id/surface",

package/src/runtime/routes/conversation-query-routes.ts

@@ -14,6 +14,7 @@
  * GET    /v1/messages/:id/content       — full message content
  * GET    /v1/messages/:id/llm-context   — LLM request logs for a message
  * GET    /v1/llm-request-logs/:id/payload — raw payload for a single log
+ * GET    /v1/llm-request-logs/:id/context — normalized context for a single log
  * DELETE /v1/messages/queued/:id        — delete queued message
  * POST   /v1/messages/queued/:id/steer — steer to a queued message
  */
@@ -21,6 +22,7 @@
 import { z } from "zod";
 
 import { LlmContextResponseSchema } from "../../api/responses/llm-context-response.js";
+import { LLMRequestLogEntrySchema } from "../../api/responses/llm-request-log-entry.js";
 import {
   deepMergeOverwrite,
   fillContextDefaultsForMissingKeys,
@@ -236,7 +238,26 @@ function applyStoredProviderToLlmContextResult(
   return { ...normalized, summary };
 }
 
-function normalizeLlmContextLog(log: LogRow): LlmContextRouteResult & {
+/**
+ * `full` returns the complete normalized entry including request/response
+ * sections; `summary` omits the sections so list responses stay small —
+ * sections for a single call are fetched lazily through
+ * `/v1/llm-request-logs/{logId}/context`.
+ */
+type LlmContextView = "full" | "summary";
+
+function resolveLlmContextView(view: string | undefined): LlmContextView {
+  if (view === undefined || view === "full") return "full";
+  if (view === "summary") return "summary";
+  throw new BadRequestError(
+    `Invalid view parameter: ${view}. Expected "full" or "summary".`,
+  );
+}
+
+function normalizeLlmContextLog(
+  log: LogRow,
+  view: LlmContextView = "full",
+): LlmContextRouteResult & {
   id: string;
   requestPayload: null;
   responsePayload: null;
@@ -283,6 +304,9 @@ function normalizeLlmContextLog(log: LogRow): LlmContextRouteResult & {
     // existing `agent_loop_exit_reason` column tells it WHICH error fired.
     callSite: log.callSite ?? null,
     ...result,
+    ...(view === "summary"
+      ? { requestSections: undefined, responseSections: undefined }
+      : {}),
   };
 }
 
@@ -898,11 +922,15 @@ function resolveConversationKind(
   return "user";
 }
 
-async function handleGetLlmContext({ pathParams = {} }: RouteHandlerArgs) {
+async function handleGetLlmContext({
+  pathParams = {},
+  queryParams = {},
+}: RouteHandlerArgs) {
   const messageId = pathParams.id;
   if (!messageId) {
     throw new BadRequestError("message id is required");
   }
+  const view = resolveLlmContextView(queryParams.view);
   const source = await getLlmRequestLogSource();
   const logs = await source.getRequestLogsByMessageId(messageId);
   const turnMessageIds = getAssistantMessageIdsInTurn(messageId);
@@ -932,7 +960,7 @@ async function handleGetLlmContext({ pathParams = {} }: RouteHandlerArgs) {
     messageId,
     conversationKind,
     conversationTotalEstimatedCostUsd,
-    logs: logs.map(normalizeLlmContextLog),
+    logs: logs.map((log) => normalizeLlmContextLog(log, view)),
     memoryRecall: memoryRecallLog ?? null,
     memoryV2Activation: memoryV2Activation ?? null,
     memoryV3Selection,
@@ -944,6 +972,7 @@ async function handleGetConversationLlmContext({
 }: RouteHandlerArgs) {
   const conversationKey = queryParams.conversationKey;
   const requestedConversationId = queryParams.conversationId;
+  const view = resolveLlmContextView(queryParams.view);
 
   let conversationId: string | undefined = requestedConversationId;
   if (!conversationId && conversationKey) {
@@ -1000,7 +1029,7 @@ async function handleGetConversationLlmContext({
     conversationId: conversation.id,
     conversationKind,
     conversationTotalEstimatedCostUsd,
-    logs: logs.map(normalizeLlmContextLog),
+    logs: logs.map((log) => normalizeLlmContextLog(log, view)),
     memoryRecall: null,
     memoryV2Activation: null,
     memoryV3Selection: null,
@@ -1034,6 +1063,21 @@ async function handleGetLlmRequestLogPayload({
   return { id: log.id, requestPayload, responsePayload };
 }
 
+async function handleGetLlmRequestLogContext({
+  pathParams = {},
+}: RouteHandlerArgs) {
+  const logId = pathParams.id;
+  if (!logId) {
+    throw new BadRequestError("log id is required");
+  }
+  const source = await getLlmRequestLogSource();
+  const log = await source.getRequestLogById(logId);
+  if (!log) {
+    throw new NotFoundError("log not found");
+  }
+  return normalizeLlmContextLog(log);
+}
+
 function handleDeleteQueuedMessage({
   queryParams = {},
   pathParams = {},
@@ -1322,6 +1366,13 @@ export const ROUTES: RouteDefinition[] = [
         schema: { type: "string" },
         description: "Internal conversation identifier.",
       },
+      {
+        name: "view",
+        required: false,
+        schema: { type: "string", enum: ["full", "summary"] },
+        description:
+          "Response shape. 'summary' omits per-log request/response sections; defaults to 'full'.",
+      },
     ],
     responseBody: LlmContextResponseSchema,
     handler: handleGetConversationLlmContext,
@@ -1338,6 +1389,15 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Return request/response logs and memory recall data for a specific message.",
     tags: ["messages"],
+    queryParams: [
+      {
+        name: "view",
+        required: false,
+        schema: { type: "string", enum: ["full", "summary"] },
+        description:
+          "Response shape. 'summary' omits per-log request/response sections; defaults to 'full'.",
+      },
+    ],
     responseBody: LlmContextResponseSchema,
     handler: handleGetLlmContext,
   },
@@ -1360,6 +1420,21 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleGetLlmRequestLogPayload,
   },
+  {
+    operationId: "llm_request_logs_context_get",
+    endpoint: "llm-request-logs/:id/context",
+    method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get normalized context for a single LLM request log",
+    description:
+      "Return the normalized summary and request/response sections for a specific log entry.",
+    tags: ["messages"],
+    responseBody: LLMRequestLogEntrySchema,
+    handler: handleGetLlmRequestLogContext,
+  },
   {
     operationId: "messages_queued_delete",
     endpoint: "messages/queued/:id",

package/src/runtime/routes/gateway-log-routes.ts

@@ -1,80 +1,30 @@
 /**
- * Gateway log tail route — gateway HTTP proxy.
+ * Gateway log tail route — gateway IPC proxy.
  *
- * The handler makes a single HTTP call to the gateway's log-tail API
- * and surfaces the body's `.error` message on non-OK responses.
+ * The handler calls the gateway over the local IPC socket so the assistant
+ * does not need gateway signing material.
  */
-import { z } from "zod";
+import {
+  type GatewayLogsTailIpcResponse,
+  GatewayLogsTailIpcResponseSchema,
+  GatewayLogsTailRouteParamsSchema,
+} from "@vellumai/gateway-client/gateway-ipc-contracts";
 
-import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import { ipcCallPersistent } from "../../ipc/gateway-client.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
-// ── Shared helper ───────────────────────────────────────────────────────
-
-async function gatewayFetch(
-  path: string,
-  init?: RequestInit,
-): Promise<unknown> {
-  const base = getGatewayInternalBaseUrl();
-  const res = await fetch(`${base}${path}`, init);
-  if (!res.ok) {
-    let message = `Gateway request failed (${res.status})`;
-    try {
-      const body = (await res.json()) as { error?: unknown };
-      if (typeof body.error === "string") {
-        message = body.error;
-      }
-    } catch {
-      // ignore JSON parse failures
-    }
-    throw new Error(message);
-  }
-  return res.json();
-}
-
-// ── Schemas ─────────────────────────────────────────────────────────────
-
-const LEVEL_NAMES = [
-  "trace",
-  "debug",
-  "info",
-  "warn",
-  "error",
-  "fatal",
-] as const;
-
-const GatewayLogsTailParams = z
-  .object({
-    n: z.coerce.number().int().min(1).max(1000).optional(),
-    level: z.enum(LEVEL_NAMES).optional(),
-    module: z.string().optional(),
-  })
-  .strict();
-
-const GatewayLogsTailResponseSchema = z.object({
-  lines: z.array(z.record(z.string(), z.unknown())),
-  truncated: z.boolean(),
-});
-type GatewayLogsTailResponse = z.infer<typeof GatewayLogsTailResponseSchema>;
-
 // ── Handlers ────────────────────────────────────────────────────────────
 
 async function handleGatewayLogsTail({
   queryParams = {},
   body = {},
-}: RouteHandlerArgs): Promise<GatewayLogsTailResponse> {
+}: RouteHandlerArgs): Promise<GatewayLogsTailIpcResponse> {
   // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
   const source = Object.keys(queryParams).length > 0 ? queryParams : body;
-  const p = GatewayLogsTailParams.parse(source);
-  const qs = new URLSearchParams();
-  if (p.n !== undefined) qs.set("n", String(p.n));
-  if (p.level !== undefined) qs.set("level", p.level);
-  if (p.module !== undefined) qs.set("module", p.module);
-  const query = qs.toString();
-  return gatewayFetch(
-    `/v1/logs/tail${query ? `?${query}` : ""}`,
-  ) as Promise<GatewayLogsTailResponse>;
+  const p = GatewayLogsTailRouteParamsSchema.parse(source);
+  const result = await ipcCallPersistent("gateway_logs_tail", p);
+  return GatewayLogsTailIpcResponseSchema.parse(result);
 }
 
 // ── Route definitions ───────────────────────────────────────────────────
@@ -93,7 +43,7 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Return the last N structured log entries from the gateway log files.",
     tags: ["gateway-logs"],
-    responseBody: GatewayLogsTailResponseSchema,
+    responseBody: GatewayLogsTailIpcResponseSchema,
     queryParams: [
       {
         name: "n",

package/src/runtime/routes/home-feed-routes.ts

@@ -29,6 +29,7 @@ import {
   HomeFeedResponseSchema,
 } from "../../api/responses/home.js";
 import { patchFeedItemStatus, readHomeFeed } from "../../home/feed-writer.js";
+import { revalidateHomeContentInBackground } from "../../home/home-content-refresh.js";
 import { getPersonalizedGreeting } from "../../home/home-greeting.js";
 import { getSuggestedPrompts } from "../../home/suggested-prompts.js";
 import {
@@ -139,6 +140,15 @@ export async function handleGetHomeFeed({
 
   const now = new Date();
 
+  // Stale-while-revalidate: serve whatever is cached right now and kick
+  // off a bounded background regeneration of any stale LLM content. The
+  // refresh publishes `home_feed_updated` when fresh content lands, so
+  // connected clients refetch and the personalized content swaps in.
+  // This is the accepted exception to GET-handler idempotency documented
+  // in `src/runtime/AGENTS.md` — the handler itself stays read-only and
+  // returns immediately with cached/fallback copy.
+  revalidateHomeContentInBackground();
+
   const personalizedGreeting = getPersonalizedGreeting();
   const suggestedPrompts = await getSuggestedPrompts();
 

package/src/runtime/routes/identity-intro-cache.ts

@@ -25,7 +25,7 @@ import { getWorkspacePromptPath } from "../../util/platform.js";
 // Constants
 // ---------------------------------------------------------------------------
 
-const CACHE_TTL_MS = 2 * 24 * 60 * 60 * 1000; // 2 days
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
 
 const CHECKPOINT_KEY_GREETINGS = "identity:intro:greetings";
 const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";

package/src/runtime/routes/identity-routes.ts

@@ -7,7 +7,6 @@ import { availableParallelism, cpus, totalmem } from "node:os";
 
 import { z } from "zod";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getCpuLimit, getIsPlatform } from "../../config/env-registry.js";
 import { resolveCallSiteConfig } from "../../config/llm-resolver.js";
 import { getConfig } from "../../config/loader.js";
@@ -36,7 +35,7 @@ import {
   readWorkspaceIdentityIntro,
   setCachedIntro,
 } from "./identity-intro-cache.js";
-import type { RouteDefinition } from "./types.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 interface MemoryInfo {
   currentMb: number;
@@ -413,12 +412,12 @@ const FALLBACK_GREETINGS = [
   "Ready when you are.",
 ];
 
-const GENERATED_GREETING_LIMIT = 4;
+const GENERATED_GREETING_LIMIT = 5;
 const GREETING_GENERATION_TIMEOUT_MS = 10_000;
 const GREETING_GENERATION_FAILURE_COOLDOWN_MS = 60_000;
 const EMPTY_STATE_GREETING_CALLSITE = "emptyStateGreeting" as const;
-const EMPTY_STATE_DYNAMIC_GREETINGS_FLAG =
-  "empty-state-dynamic-greetings" as const;
+const EXPLICIT_TIME_OF_DAY_PATTERN =
+  /\b(?:morning|afternoon|evening|tonight|midnight|noon|sunrise|sunset)\b/i;
 
 type IdentityIntroSource = "workspace" | "cache" | "fallback";
 
@@ -445,21 +444,18 @@ function identityIntroResponse(
   };
 }
 
-function getIdentityIntro(): IdentityIntroResponse {
+function getIdentityIntro({
+  queryParams = {},
+}: RouteHandlerArgs = {}): IdentityIntroResponse {
+  const localTimeContext = buildLocalTimeContext(queryParams);
+
   // 1. User-defined greetings from SOUL.md `## Greetings`
   const workspaceGreetings = readWorkspaceGreetings();
   if (workspaceGreetings) {
     return identityIntroResponse(workspaceGreetings, "workspace");
   }
 
-  const config = getConfig();
-  if (
-    !isAssistantFeatureFlagEnabled(EMPTY_STATE_DYNAMIC_GREETINGS_FLAG, config)
-  ) {
-    return identityIntroResponse(FALLBACK_GREETINGS, "fallback");
-  }
-
-  // 2. Cached LLM-generated greetings (populated by background refresh)
+  // 2. Cached LLM-generated greetings
   const cached = getCachedIntro();
   if (cached) {
     return identityIntroResponse(cached.greetings, "cache");
@@ -471,7 +467,7 @@ function getIdentityIntro(): IdentityIntroResponse {
   if (identityIntro) {
     // Still trigger background generation so the next request gets
     // LLM-generated greetings instead of the static tagline.
-    const refreshing = triggerEmptyStateGreetingGeneration();
+    const refreshing = triggerEmptyStateGreetingGeneration(localTimeContext);
     return identityIntroResponse(
       [identityIntro, ...FALLBACK_GREETINGS],
       "workspace",
@@ -480,13 +476,50 @@ function getIdentityIntro(): IdentityIntroResponse {
   }
 
   // 4. Trigger fresh generation without blocking the empty-state UI.
-  const refreshing = triggerEmptyStateGreetingGeneration();
+  const refreshing = triggerEmptyStateGreetingGeneration(localTimeContext);
 
   // 5. Generic fallback only when generation is unavailable.
   return identityIntroResponse(FALLBACK_GREETINGS, "fallback", refreshing);
 }
 
-function triggerEmptyStateGreetingGeneration(): boolean {
+function buildLocalTimeContext(
+  queryParams: Record<string, string>,
+): string | null {
+  const rawHour = queryParams.localHour;
+  const rawMinute = queryParams.localMinute;
+  if (rawHour === undefined || rawMinute === undefined) {
+    return null;
+  }
+
+  const hour = Number(rawHour);
+  const minute = Number(rawMinute);
+  if (
+    !Number.isInteger(hour) ||
+    !Number.isInteger(minute) ||
+    hour < 0 ||
+    hour > 23 ||
+    minute < 0 ||
+    minute > 59
+  ) {
+    return null;
+  }
+
+  const period =
+    hour >= 5 && hour < 12
+      ? "morning"
+      : hour >= 12 && hour < 17
+        ? "afternoon"
+        : hour >= 17 && hour < 21
+          ? "evening"
+          : "late night";
+  const paddedHour = String(hour).padStart(2, "0");
+  const paddedMinute = String(minute).padStart(2, "0");
+  return `${period} (${paddedHour}:${paddedMinute})`;
+}
+
+function triggerEmptyStateGreetingGeneration(
+  localTimeContext: string | null,
+): boolean {
   if (greetingGenerationInFlight) {
     return true;
   }
@@ -501,7 +534,7 @@ function triggerEmptyStateGreetingGeneration(): boolean {
 
   greetingGenerationInFlight = new Promise<void>((resolve) => {
     queueMicrotask(() => {
-      void generateEmptyStateGreetings()
+      void generateEmptyStateGreetings(localTimeContext)
         .then((greetings) => {
           lastGreetingGenerationFailureAt = greetings === null ? Date.now() : 0;
         })
@@ -515,7 +548,9 @@ function triggerEmptyStateGreetingGeneration(): boolean {
   return true;
 }
 
-async function generateEmptyStateGreetings(): Promise<string[] | null> {
+async function generateEmptyStateGreetings(
+  localTimeContext: string | null,
+): Promise<string[] | null> {
   try {
     const provider = await getConfiguredProvider(EMPTY_STATE_GREETING_CALLSITE);
     if (!provider) {
@@ -530,12 +565,18 @@ async function generateEmptyStateGreetings(): Promise<string[] | null> {
       excludeBootstrap: true,
       excludeCustomPrefix: true,
     });
+    const localTimeInstruction = localTimeContext
+      ? ` Current user-local time for subtle tone only: ${localTimeContext}.`
+      : "";
     const result = await runBtwSidechain({
       content:
         `Generate ${GENERATED_GREETING_LIMIT} short first-person greeting options for the empty new-chat screen. ` +
         "Use the assistant identity, voice, and relationship guidance from IDENTITY.md and SOUL.md. " +
         "Each greeting should feel personal and inviting, not like a generic assistant introduction. " +
-        "Return only a JSON array of strings. No markdown, keys, or explanation.",
+        "Return only a JSON array of strings. No markdown, keys, or explanation. " +
+        "Generated greetings are cached for 4 hours, so do not mention the current time " +
+        "or use explicit time-of-day words like morning, afternoon, evening, or tonight." +
+        localTimeInstruction,
       provider,
       systemPrompt,
       messages: [],
@@ -601,6 +642,7 @@ function normalizeGeneratedGreetings(values: unknown[]): string[] {
       .replace(/^["'`]+|["'`]+$/g, "")
       .trim();
     if (!greeting) continue;
+    if (EXPLICIT_TIME_OF_DAY_PATTERN.test(greeting)) continue;
 
     const key = greeting.toLowerCase();
     if (seen.has(key)) continue;
@@ -758,6 +800,20 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Returns greetings sourced from SOUL.md, the generated cache, or generic fallbacks while background generation refreshes the cache.",
     tags: ["identity"],
+    queryParams: [
+      {
+        name: "localHour",
+        schema: { type: "integer", minimum: 0, maximum: 23 },
+        description:
+          "Optional client-local hour of day used only when refreshing generated greetings.",
+      },
+      {
+        name: "localMinute",
+        schema: { type: "integer", minimum: 0, maximum: 59 },
+        description:
+          "Optional client-local minute used only when refreshing generated greetings.",
+      },
+    ],
     responseBody: z.object({
       greetings: z.array(z.string()),
       text: z.string(),