Add web AI client time context

Author: Rabithua

server/utils/ai/agent/clientRuntime.ts

@@ -4,6 +4,7 @@ import type { ChatToolCall } from '../client';
 import { getNativeRoteTools } from './tools';
 import {
   DEFAULT_AGENT_POLICY,
+  type RoteAgentClientContext,
   type RoteAgentClientState,
   type RoteAgentContext,
   type RoteAgentRequest,
@@ -14,6 +15,42 @@ function sourceKey(source: SemanticSearchResult): string {
   return `${source.sourceType}:${source.sourceId}`;
 }
 
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function sanitizeString(value: unknown, maxLength: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, maxLength) : undefined;
+}
+
+function sanitizeUtcOffsetMinutes(value: unknown): number | undefined {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return undefined;
+  const minutes = Math.trunc(numeric);
+  return minutes >= -14 * 60 && minutes <= 14 * 60 ? minutes : undefined;
+}
+
+function sanitizeClientContext(value: unknown): RoteAgentClientContext | null {
+  const raw = asRecord(value);
+  if (!Object.keys(raw).length) return null;
+
+  const context: RoteAgentClientContext = {
+    nowIso: sanitizeString(raw.nowIso, 64),
+    localDate: sanitizeString(raw.localDate, 32),
+    localDateTime: sanitizeString(raw.localDateTime, 64),
+    timeZone: sanitizeString(raw.timeZone, 80),
+    utcOffsetMinutes: sanitizeUtcOffsetMinutes(raw.utcOffsetMinutes),
+    locale: sanitizeString(raw.locale, 32),
+    calendar: sanitizeString(raw.calendar, 32),
+  };
+
+  return Object.values(context).some((item) => item !== undefined) ? context : null;
+}
+
 class ClientSourceCollector {
   private sourceKeys: string[];
   private sourcesByKey = new Map<string, SemanticSearchResult>();
@@ -85,6 +122,7 @@ function sanitizeRequest(value: unknown): RoteAgentRequest {
     pendingPlan: request.pendingPlan,
     clarificationAnswer:
       typeof request.clarificationAnswer === 'string' ? request.clarificationAnswer : undefined,
+    clientContext: sanitizeClientContext(request.clientContext),
   };
 }
 
@@ -100,6 +138,7 @@ function sanitizeState(value: unknown): RoteAgentClientState {
           .slice(0, 500)
       : [],
     selectedContext: state.selectedContext || null,
+    clientContext: sanitizeClientContext(state.clientContext),
     stateVersion: Number.isFinite(state.stateVersion) ? Number(state.stateVersion) : 1,
   };
 }
@@ -121,6 +160,9 @@ export async function executeClientRoteTool(params: {
 
   const request = sanitizeRequest(params.request);
   const state = sanitizeState(params.state);
+  if (!state.clientContext && request.clientContext) {
+    state.clientContext = request.clientContext;
+  }
   const collector = new ClientSourceCollector(params.sourceKeys);
   const call: ChatToolCall = {
     id: `client_${Date.now()}_${Math.random().toString(16).slice(2)}`,

web/src/utils/aiApi.ts

@@ -172,6 +172,7 @@ export interface AiAgentClientState {
     selectedSourceIds?: string[];
     selectedTags?: string[];
   } | null;
+  clientContext?: AiClientRequestContext | null;
   stateVersion?: number;
 }
 
@@ -243,10 +244,87 @@ export type AiChatPayload = {
   excludeIds?: string[];
   history?: { role: 'user' | 'assistant'; content: string }[];
   state?: AiAgentClientState | null;
+  clientContext?: AiClientRequestContext | null;
   debug?: boolean;
   enableThinking?: boolean;
 };
 
+export interface AiClientRequestContext {
+  nowIso: string;
+  localDate: string;
+  localDateTime: string;
+  timeZone?: string;
+  utcOffsetMinutes: number;
+  locale?: string;
+  calendar?: string;
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+function formatUtcOffset(minutes: number): string {
+  const sign = minutes >= 0 ? '+' : '-';
+  const absolute = Math.abs(minutes);
+  return `${sign}${padDatePart(Math.floor(absolute / 60))}:${padDatePart(absolute % 60)}`;
+}
+
+export function createAiClientRequestContext(now = new Date()): AiClientRequestContext {
+  const resolvedOptions = Intl.DateTimeFormat().resolvedOptions();
+  const utcOffsetMinutes = -now.getTimezoneOffset();
+  const localDate = [
+    now.getFullYear(),
+    padDatePart(now.getMonth() + 1),
+    padDatePart(now.getDate()),
+  ].join('-');
+  const localTime = [
+    padDatePart(now.getHours()),
+    padDatePart(now.getMinutes()),
+    padDatePart(now.getSeconds()),
+  ].join(':');
+
+  return {
+    nowIso: now.toISOString(),
+    localDate,
+    localDateTime: `${localDate}T${localTime}${formatUtcOffset(utcOffsetMinutes)}`,
+    timeZone: resolvedOptions.timeZone,
+    utcOffsetMinutes,
+    locale: typeof navigator !== 'undefined' ? navigator.language : resolvedOptions.locale,
+    calendar: resolvedOptions.calendar,
+  };
+}
+
+export function buildAiClientTimeContextMessage(context: AiClientRequestContext): string {
+  return [
+    'Use the current request time context for relative date phrases.',
+    `Client now (UTC): ${context.nowIso}`,
+    `Client local date: ${context.localDate}`,
+    `Client local date/time: ${context.localDateTime}`,
+    context.timeZone ? `Client time zone: ${context.timeZone}` : null,
+    `Client UTC offset minutes: ${context.utcOffsetMinutes}`,
+    context.locale ? `Client locale: ${context.locale}` : null,
+    context.calendar ? `Client calendar: ${context.calendar}` : null,
+    'Resolve relative date phrases such as today, yesterday, this month, last month, 最近, 本月, and 上月 using this context.',
+    'For Rote search tools, prefer structured timeRange preset/rolling/relative_between or pass the original phrase as timeExpression. Use from/to only for explicit absolute dates.',
+  ]
+    .filter((line): line is string => Boolean(line))
+    .join('\n');
+}
+
+export function withAiClientRequestContext(payload: AiChatPayload): AiChatPayload {
+  const clientContext = payload.clientContext || createAiClientRequestContext();
+  return {
+    ...payload,
+    clientContext,
+    state: payload.state
+      ? {
+          ...payload.state,
+          clientContext: payload.state.clientContext || clientContext,
+        }
+      : payload.state,
+  };
+}
+
 export const getClientAgentBootstrap = () =>
   get('/ai/client-agent/bootstrap').then((res) => res.data as ClientAgentBootstrap);
 
@@ -256,14 +334,26 @@ export const executeClientAgentTool = (payload: {
   request: AiChatPayload;
   state?: AiAgentClientState | null;
   sourceKeys?: string[];
-}) =>
-  post('/ai/client-agent/tools/execute', payload).then((res) => res.data as ClientAgentToolResult);
+}) => {
+  const request = withAiClientRequestContext(payload.request);
+  return post('/ai/client-agent/tools/execute', {
+    ...payload,
+    request,
+    state: payload.state
+      ? {
+          ...payload.state,
+          clientContext: payload.state.clientContext || request.clientContext,
+        }
+      : payload.state,
+  }).then((res) => res.data as ClientAgentToolResult);
+};
 
 async function createAiStreamRequest(
   endpoint: '/ai/chat/stream' | '/ai/agent/stream',
   payload: AiChatPayload,
   signal?: AbortSignal
 ) {
+  const requestPayload = withAiClientRequestContext(payload);
   let token = authService.getAccessToken();
   const request = () =>
     fetch(`${getApiUrl()}${endpoint}`, {
@@ -272,7 +362,7 @@ async function createAiStreamRequest(
         'Content-Type': 'application/json',
         ...(token ? { Authorization: `Bearer ${token}` } : {}),
       },
-      body: JSON.stringify(payload),
+      body: JSON.stringify(requestPayload),
       signal,
     });
 

web/src/utils/localAiAgent.ts

@@ -1,7 +1,9 @@
 import type { PersonalAiProviderConfig } from '@/state/localAi';
 import {
+  buildAiClientTimeContextMessage,
   executeClientAgentTool,
   getClientAgentBootstrap,
+  withAiClientRequestContext,
   type AiAgentClientState,
   type AiChatPayload,
   type AiChatStreamHandlers,
@@ -40,18 +42,23 @@ export async function localAiAgentStream(params: {
   enableThinking: boolean;
   signal?: AbortSignal;
 }) {
+  const payload = withAiClientRequestContext(params.payload);
+  const clientContext = payload.clientContext;
   const bootstrap = params.toolsAvailable ? await getClientAgentBootstrap() : null;
   const messages: LocalChatMessage[] = [
     {
       role: 'system',
       content: bootstrap?.systemPrompt || PERSONAL_ASSISTANT_PROMPT,
     },
-    ...(params.payload.history || []).slice(-8),
-    { role: 'user', content: params.payload.message },
+    ...(clientContext
+      ? [{ role: 'system' as const, content: buildAiClientTimeContextMessage(clientContext) }]
+      : []),
+    ...(payload.history || []).slice(-8),
+    { role: 'user', content: payload.message },
   ];
   const sourceMap = new Map<string, AiSemanticResult>();
   let sourceKeys: string[] = [];
-  let state: AiAgentClientState = params.payload.state || { stateVersion: 1, seenSourceIds: [] };
+  let state: AiAgentClientState = payload.state || { stateVersion: 1, seenSourceIds: [] };
   let toolCallCount = 0;
   let hasAnswer = false;
   const availableToolNames = new Set(bootstrap?.tools.map((tool) => tool.function.name) || []);
@@ -142,7 +149,7 @@ export async function localAiAgentStream(params: {
       const result = await executeClientAgentTool({
         toolName: call.function.name,
         arguments: args,
-        request: params.payload,
+        request: payload,
         state,
         sourceKeys,
       });