feat(timezone): recreate v1 TZ-aware formatting + scheduling behavior

The agent needs to perceive times in the user's timezone, not UTC.
Dropping this in the v1→v2 port produced a class of bugs where the agent
would schedule tasks for the wrong hour, suggest dinner at midnight, etc.
This restores v1 parity.

Container side:
- New container/agent-runner/src/timezone.ts mirrors src/timezone.ts with
  isValidTimezone / resolveTimezone / formatLocalTime, plus:
  * TIMEZONE constant resolved at load from process.env.TZ (host sets this
    from src/container-runner.ts:254)
  * parseZonedToUtc(input, tz) — treats a naive ISO as wall-clock time in
    `tz`, returns the corresponding UTC Date. Strings with Z or offset
    are passed through.

- formatter.ts:
  * formatMessages() now prepends <context timezone="IANA"/>\n — matches
    v1 src/v1/router.ts:20-22
  * formatSingleChat uses formatLocalTime(ts, TIMEZONE) instead of a
    home-rolled HH:MM 24h formatter → outputs like "Jun 15, 2026, 8:00 AM"
  * reply_to="<id>" attribute + <quoted_message from="X">Y</quoted_message>
    element — matches v1 format exactly; old <reply-to/> shape is gone
  * stripInternalTags() exported for the dispatch path to reuse

- poll-loop.ts uses the exported stripInternalTags() instead of inline regex.

- mcp-tools/scheduling.ts:
  * schedule_task/update_task descriptions now explicitly document that
    processAfter accepts either UTC or naive local time (interpreted in
    the user's TZ from the context header)
  * handlers normalize through parseZonedToUtc() and store a UTC ISO

Host side:
- src/modules/scheduling/recurrence.ts passes { tz: TIMEZONE } to
  CronExpressionParser.parse. Without this, "0 9 * * *" fires at 09:00
  UTC instead of 09:00 user-local — this was the v1 behavior
  (src/v1/task-scheduler.ts:20-49).

Tests:
- container/agent-runner/src/timezone.test.ts — mirror of src/timezone.test.ts
  + new parseZonedToUtc cases
- container/agent-runner/src/formatter.test.ts — context header, reply_to,
  quoted_message, XML escaping, stripInternalTags (ported from v1
  formatting.test.ts)
- src/modules/scheduling/recurrence.test.ts — cron TZ respected, completed
  rows only cloned when recurrence is set

Ref: docs/v1-vs-v2/ACTION-ITEMS.md item 18 + timezone-formatting-v1-recreation.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
2026-04-20 01:09:14 +03:00
parent 0283391e0a
commit dcfa12ea06
8 changed files with 549 additions and 30 deletions

View File

@@ -1,5 +1,6 @@
import { findByRouting } from './destinations.js';
import type { MessageInRow } from './db/messages-in.js';
import { TIMEZONE, formatLocalTime } from './timezone.js';
/**
* Command categories for messages starting with '/'.
@@ -92,10 +93,19 @@ export function extractRouting(messages: MessageInRow[]): RoutingContext {
/**
* Format a batch of messages_in rows into a prompt string.
*
* Prepends a `<context timezone="<IANA>" />` header so the agent always knows
* what timezone it's in — every timestamp it sees in message bodies is the
* user's local time, and every time it produces (schedules, suggests) should
* be interpreted as local time in that same zone. This header is v1 behavior
* (src/v1/router.ts:20-22); dropping it led to misinterpretations where the
* agent scheduled tasks for the wrong hour.
*
* Strips routing fields — the agent never sees platform_id, channel_type, thread_id.
*/
export function formatMessages(messages: MessageInRow[]): string {
if (messages.length === 0) return '';
const header = `<context timezone="${escapeXml(TIMEZONE)}" />\n`;
if (messages.length === 0) return header;
// Group by kind
const chatMessages = messages.filter((m) => m.kind === 'chat' || m.kind === 'chat-sdk');
@@ -118,7 +128,7 @@ export function formatMessages(messages: MessageInRow[]): string {
parts.push(...systemMessages.map(formatSystemMessage));
}
return parts.join('\n\n');
return header + parts.join('\n\n');
}
function formatChatMessages(messages: MessageInRow[]): string {
@@ -137,9 +147,10 @@ function formatChatMessages(messages: MessageInRow[]): string {
function formatSingleChat(msg: MessageInRow): string {
const content = parseContent(msg.content);
const sender = content.sender || content.author?.fullName || content.author?.userName || 'Unknown';
const time = formatTime(msg.timestamp);
const time = formatLocalTime(msg.timestamp, TIMEZONE);
const text = content.text || '';
const idAttr = msg.seq != null ? ` id="${msg.seq}"` : '';
const replyAttr = content.replyTo?.id ? ` reply_to="${escapeXml(String(content.replyTo.id))}"` : '';
const replyPrefix = formatReplyContext(content.replyTo);
const attachmentsSuffix = formatAttachments(content.attachments);
@@ -154,7 +165,7 @@ function formatSingleChat(msg: MessageInRow): string {
? ` from="unknown:${escapeXml(msg.channel_type || '')}:${escapeXml(msg.platform_id || '')}"`
: '';
return `<message${idAttr}${fromAttr} sender="${escapeXml(sender)}" time="${time}">${replyPrefix}${escapeXml(text)}${attachmentsSuffix}</message>`;
return `<message${idAttr}${fromAttr} sender="${escapeXml(sender)}" time="${escapeXml(time)}"${replyAttr}>${replyPrefix}${escapeXml(text)}${attachmentsSuffix}</message>`;
}
function formatTaskMessage(msg: MessageInRow): string {
@@ -179,13 +190,22 @@ function formatSystemMessage(msg: MessageInRow): string {
return `[SYSTEM RESPONSE]\n\nAction: ${content.action || 'unknown'}\nStatus: ${content.status || 'unknown'}\nResult: ${JSON.stringify(content.result || null)}`;
}
/**
* Render the quoted original inside the <message> body.
*
* Matches v1 format (src/v1/router.ts:10-18): `<quoted_message from="X">Y</quoted_message>`.
* Requires BOTH sender and text — if only id is present the reply_to attribute
* on the parent <message> carries the link without an inline preview.
*
* No truncation here (v1 didn't truncate).
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function formatReplyContext(replyTo: any): string {
if (!replyTo) return '';
const sender = replyTo.sender || 'Unknown';
const text = replyTo.text || '';
const preview = text.length > 100 ? text.slice(0, 100) + '…' : text;
return `\n<reply-to sender="${escapeXml(sender)}">${escapeXml(preview)}</reply-to>\n`;
const sender = replyTo.sender;
const text = replyTo.text;
if (!sender || !text) return '';
return `\n <quoted_message from="${escapeXml(sender)}">${escapeXml(text)}</quoted_message>\n`;
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -213,15 +233,15 @@ function parseContent(json: string): any {
}
}
function formatTime(timestamp: string): string {
try {
const d = new Date(timestamp);
return `${d.getHours().toString().padStart(2, '0')}:${d.getMinutes().toString().padStart(2, '0')}`;
} catch {
return timestamp;
}
}
function escapeXml(str: string): string {
return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
}
/**
* Strip `<internal>...</internal>` blocks from agent output, then trim.
* Ported from v1 (src/v1/router.ts:25-27). Used to remove the agent's
* own scratchpad/reasoning before a reply goes out over a channel.
*/
export function stripInternalTags(text: string): string {
return text.replace(/<internal>[\s\S]*?<\/internal>/g, '').trim();
}