@llblab/pi-telegram 0.11.0 → 0.11.2

package/lib/config.ts

@@ -35,6 +35,19 @@ export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConf
   timeout?: number;
 }
 
+export type TelegramTimeMode = "hidden" | "always" | "interval";
+
+export interface TelegramTimeConfig {
+  injectionMode?: TelegramTimeMode;
+  interval?: number;
+}
+
+export interface ResolvedTelegramTimeConfig {
+  injectionMode: TelegramTimeMode;
+  interval: number;
+  timezone: string;
+}
+
 export interface TelegramConfig {
   botToken?: string;
   botUsername?: string;
@@ -50,6 +63,7 @@ export interface TelegramConfig {
     /** Whether to attach the provider's transcriptText as caption on voice messages */
     sendTranscript?: boolean;
   };
+  time?: TelegramTimeConfig;
 }
 
 export interface TelegramConfigStore {
@@ -211,6 +225,56 @@ export function createTelegramVoiceReplyModeSetter(
   };
 }
 
+function getSystemTimezone(): string {
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return tz && tz.length > 0 ? tz : "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export function resolveTelegramTimeConfig(
+  raw: TelegramTimeConfig | undefined,
+): ResolvedTelegramTimeConfig {
+  const injectionMode: TelegramTimeMode =
+    raw?.injectionMode === "always" || raw?.injectionMode === "interval"
+      ? raw.injectionMode
+      : "hidden";
+  const interval =
+    typeof raw?.interval === "number" && raw.interval > 0
+      ? raw.interval
+      : 60 * 60 * 1000;
+  const timezone = getSystemTimezone();
+  return { injectionMode, interval, timezone };
+}
+
+export function createTelegramTimeConfigGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => ResolvedTelegramTimeConfig {
+  return () => resolveTelegramTimeConfig(configStore.get().time);
+}
+
+export function createTelegramTimeInjectionModeGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => TelegramTimeMode {
+  return () => resolveTelegramTimeConfig(configStore.get().time).injectionMode;
+}
+
+export function createTelegramTimeInjectionModeSetter(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+): (injectionMode: TelegramTimeMode) => Promise<void> {
+  return async (injectionMode) => {
+    const current = configStore.get();
+    const next = {
+      ...current,
+      time: { ...(current.time ?? {}), injectionMode },
+    };
+    configStore.set(next);
+    await configStore.persist(next);
+  };
+}
+
 export function createTelegramProactivePushChatIdGetter(deps: {
   getActiveTurnChatId: () => number | undefined;
   getAllowedUserId: () => number | undefined;

package/lib/lifecycle.ts

@@ -10,6 +10,8 @@ import type {
   BeforeAgentStartEvent,
   ExtensionAPI,
   ExtensionContext,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
   SessionShutdownEvent,
   SessionStartEvent,
 } from "./pi.ts";
@@ -50,6 +52,14 @@ export interface TelegramLifecycleRegistrationDeps {
     event: SessionShutdownEvent,
     ctx: ExtensionContext,
   ) => Promise<void>;
+  onSessionBeforeCompact?: (
+    event: SessionBeforeCompactEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
+  onSessionCompact?: (
+    event: SessionCompactEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
   onBeforeAgentStart: (
     event: BeforeAgentStartEvent,
     ctx: ExtensionContext,
@@ -92,6 +102,76 @@ export interface TelegramSessionLifecycleHooks {
   ) => Promise<void>;
 }
 
+type TelegramLifecycleTimer = number | ReturnType<typeof setTimeout>;
+
+export interface TelegramCompactionObserverRuntimeDeps<TContext> {
+  setCompactionInProgress: (inProgress: boolean) => void;
+  updateStatus: (ctx: TContext) => void;
+  requestDeferredDispatchNextQueuedTelegramTurn: (
+    dispatch: (ctx: TContext) => void,
+  ) => void;
+  dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
+  recordRuntimeEvent?: (category: string, error: unknown) => void;
+  timeoutMs?: number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => TelegramLifecycleTimer;
+  clearTimer?: (timer: TelegramLifecycleTimer) => void;
+}
+
+export interface TelegramCompactionObserverRuntime<TContext> {
+  onSessionBeforeCompact: (
+    event: SessionBeforeCompactEvent,
+    ctx: TContext,
+  ) => void;
+  onSessionCompact: (event: SessionCompactEvent, ctx: TContext) => void;
+  onSessionShutdown: () => void;
+}
+
+export function createTelegramCompactionObserverRuntime<TContext>(
+  deps: TelegramCompactionObserverRuntimeDeps<TContext>,
+): TelegramCompactionObserverRuntime<TContext> {
+  const timeoutMs = deps.timeoutMs ?? 300_000;
+  const setTimer = deps.setTimer ?? setTimeout;
+  const clearTimer = deps.clearTimer ?? clearTimeout;
+  let fallbackTimer: TelegramLifecycleTimer | undefined;
+  const clearFallbackTimer = (): void => {
+    if (!fallbackTimer) return;
+    clearTimer(fallbackTimer);
+    fallbackTimer = undefined;
+  };
+  const requestDispatch = (): void => {
+    deps.requestDeferredDispatchNextQueuedTelegramTurn(
+      deps.dispatchNextQueuedTelegramTurn,
+    );
+  };
+  return {
+    onSessionBeforeCompact: (_event, ctx) => {
+      deps.setCompactionInProgress(true);
+      deps.updateStatus(ctx);
+      clearFallbackTimer();
+      fallbackTimer = setTimer(() => {
+        fallbackTimer = undefined;
+        deps.setCompactionInProgress(false);
+        deps.updateStatus(ctx);
+        deps.recordRuntimeEvent?.(
+          "compact",
+          new Error("Compaction observer timed out"),
+        );
+        requestDispatch();
+      }, timeoutMs);
+    },
+    onSessionCompact: (_event, ctx) => {
+      clearFallbackTimer();
+      deps.setCompactionInProgress(false);
+      deps.updateStatus(ctx);
+      requestDispatch();
+    },
+    onSessionShutdown: clearFallbackTimer,
+  };
+}
+
 export function createDedupAgentStartHook(
   dedup: { reset(): void },
   inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>,
@@ -139,6 +219,12 @@ export function registerTelegramLifecycleHooks(
   pi.on("session_shutdown", async (event, ctx) => {
     await deps.onSessionShutdown(event, ctx);
   });
+  pi.on("session_before_compact", async (event, ctx) => {
+    await deps.onSessionBeforeCompact?.(event, ctx);
+  });
+  pi.on("session_compact", async (event, ctx) => {
+    await deps.onSessionCompact?.(event, ctx);
+  });
   pi.on("before_agent_start", async (event, ctx) => {
     return deps.onBeforeAgentStart(event, ctx);
   });

package/lib/menu-settings.ts

@@ -8,6 +8,7 @@ import {
   getTelegramExtensionSettingsRows,
   type TelegramSectionRegistry,
 } from "./extension-sections.ts";
+import type { TelegramTimeMode } from "./config.ts";
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { TelegramModelMenuState } from "./menu-model.ts";
 import type { MenuModel } from "./model.ts";
@@ -17,6 +18,7 @@ export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramSettingsStateDeps {
   isProactivePushEnabled: () => boolean;
+  getTimeInjectionMode: () => TelegramTimeMode;
   getVoiceReplyMode: () => TelegramVoiceReplyMode;
   isVoiceReplyModeConfigured: () => boolean;
 }
@@ -26,6 +28,7 @@ export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps
   setVoiceReplyMode: (
     mode: TelegramVoiceReplyMode | undefined,
   ) => Promise<void>;
+  setTimeInjectionMode: (mode: TelegramTimeMode) => Promise<void>;
 }
 
 export interface TelegramSettingsMenuOpenDeps<
@@ -111,8 +114,9 @@ export interface TelegramSettingsMenuRuntimeDeps<
 }
 
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
-export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>Proactive push:</b>";
-export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>Voice reply mode:</b>";
+export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
+export const TIME_INJECTION_MODE_SETTINGS_TITLE = "<b>🕒 Time injection mode:</b>";
+export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
 
 type TelegramVoiceReplyModeSetting = TelegramVoiceReplyMode | "hidden";
 
@@ -131,17 +135,24 @@ export function buildTelegramSettingsMenuText(): string {
   return SETTINGS_MENU_TITLE;
 }
 
-export function buildProactivePushSettingsText(): string {
+export function buildProactivePushSettingsText(
+  proactivePushEnabled: boolean,
+): string {
   return [
-    PROACTIVE_PUSH_SETTINGS_TITLE,
+    `${PROACTIVE_PUSH_SETTINGS_TITLE} <code>${proactivePushEnabled ? "on" : "off"}</code>`,
     "",
     "Send successful local π task results to Telegram when the bridge is connected.",
   ].join("\n");
 }
 
-export function buildVoiceReplyModeSettingsText(): string {
+export function buildVoiceReplyModeSettingsText(
+  mode: TelegramVoiceReplyMode,
+  configured = true,
+): string {
   return [
-    VOICE_REPLY_MODE_SETTINGS_TITLE,
+    `${VOICE_REPLY_MODE_SETTINGS_TITLE} <code>${getVoiceReplyModeLabel(
+      getVoiceReplyModeSetting(mode, configured),
+    )}</code>`,
     "",
     "Controls when pi-telegram converts assistant text replies into Telegram voice messages.",
     "",
@@ -152,9 +163,24 @@ export function buildVoiceReplyModeSettingsText(): string {
   ].join("\n");
 }
 
+export function buildTimeInjectionModeSettingsText(
+  mode: TelegramTimeMode,
+): string {
+  return [
+    `${TIME_INJECTION_MODE_SETTINGS_TITLE} <code>${mode}</code>`,
+    "",
+    "Controls whether Telegram-originated prompts include a compact wall-clock [time] line.",
+    "",
+    "<code>-</code> <code>hidden</code> (default): no time line is added to prompt context.",
+    "<code>-</code> <code>always</code>: add time to every Telegram turn.",
+    "<code>-</code> <code>interval</code>: add time at most once per chat interval (default: 1 hour).",
+  ].join("\n");
+}
+
 export function buildTelegramSettingsMenuReplyMarkup(
   proactivePushEnabled: boolean,
   voiceReplyMode: TelegramVoiceReplyMode,
+  timeInjectionMode: TelegramTimeMode,
   sectionRegistry?: TelegramSectionRegistry,
   voiceReplyModeConfigured = true,
 ): TelegramSettingsMenuReplyMarkup {
@@ -179,7 +205,13 @@ export function buildTelegramSettingsMenuReplyMarkup(
     ],
     [
       {
-        text: `${proactivePushEnabled ? "🟢" : "⚫️"} Proactive push`,
+        text: `🕒 Time injection: ${timeInjectionMode}`,
+        callback_data: "settings:open:time-injection",
+      },
+    ],
+    [
+      {
+        text: `📌 Proactive push: ${proactivePushEnabled ? "on" : "off"}`,
         callback_data: "settings:open:proactive",
       },
     ],
@@ -200,6 +232,7 @@ export async function openTelegramSettingsMenu<
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
       deps.getVoiceReplyMode(),
+      deps.getTimeInjectionMode(),
       sectionRegistry,
       deps.isVoiceReplyModeConfigured(),
     ),
@@ -230,6 +263,23 @@ export function buildProactivePushSettingsReplyMarkup(
   };
 }
 
+export function buildTimeInjectionModeSettingsReplyMarkup(
+  mode: TelegramTimeMode,
+): TelegramSettingsMenuReplyMarkup {
+  const modes: TelegramTimeMode[] = ["hidden", "always", "interval"];
+  return {
+    inline_keyboard: [
+      [{ text: "⬆️ Back", callback_data: "settings:list" }],
+      ...modes.map((value) => [
+        {
+          text: `${value === mode ? "🟢 " : ""}${value}`,
+          callback_data: `settings:set:time-injection:${value}`,
+        },
+      ]),
+    ],
+  };
+}
+
 export function buildVoiceReplyModeSettingsReplyMarkup(
   mode: TelegramVoiceReplyMode,
   configured = true,
@@ -263,6 +313,7 @@ export async function updateTelegramSettingsMenuMessage(
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
       deps.getVoiceReplyMode(),
+      deps.getTimeInjectionMode(),
       sectionRegistry,
       deps.isVoiceReplyModeConfigured(),
     ),
@@ -272,21 +323,31 @@ export async function updateTelegramSettingsMenuMessage(
 export async function updateProactivePushSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
+  const proactivePushEnabled = deps.isProactivePushEnabled();
+  await deps.updateSettingsMessage(
+    buildProactivePushSettingsText(proactivePushEnabled),
+    buildProactivePushSettingsReplyMarkup(proactivePushEnabled),
+  );
+}
+
+export async function updateTimeInjectionModeSettingsMessage(
+  deps: TelegramSettingsMenuCallbackDeps,
+): Promise<void> {
+  const mode = deps.getTimeInjectionMode();
   await deps.updateSettingsMessage(
-    buildProactivePushSettingsText(),
-    buildProactivePushSettingsReplyMarkup(deps.isProactivePushEnabled()),
+    buildTimeInjectionModeSettingsText(mode),
+    buildTimeInjectionModeSettingsReplyMarkup(mode),
   );
 }
 
 export async function updateVoiceReplyModeSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
+  const mode = deps.getVoiceReplyMode();
+  const configured = deps.isVoiceReplyModeConfigured();
   await deps.updateSettingsMessage(
-    buildVoiceReplyModeSettingsText(),
-    buildVoiceReplyModeSettingsReplyMarkup(
-      deps.getVoiceReplyMode(),
-      deps.isVoiceReplyModeConfigured(),
-    ),
+    buildVoiceReplyModeSettingsText(mode, configured),
+    buildVoiceReplyModeSettingsReplyMarkup(mode, configured),
   );
 }
 
@@ -311,6 +372,11 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
+  if (data === "settings:open:time-injection" || data === "settings:open:time") {
+    await updateTimeInjectionModeSettingsMessage(deps);
+    await deps.answerCallbackQuery(callbackQueryId);
+    return true;
+  }
   if (data.startsWith("settings:set:voice-reply:")) {
     const mode = data.slice("settings:set:voice-reply:".length);
     if (
@@ -328,6 +394,28 @@ export async function handleTelegramSettingsMenuCallbackAction(
       return true;
     }
   }
+  if (
+    data.startsWith("settings:set:time-injection:") ||
+    data.startsWith("settings:set:time:")
+  ) {
+    const mode = data.startsWith("settings:set:time-injection:")
+      ? data.slice("settings:set:time-injection:".length)
+      : data.slice("settings:set:time:".length);
+    const normalizedMode = mode === "off" ? "hidden" : mode;
+    if (
+      normalizedMode === "hidden" ||
+      normalizedMode === "always" ||
+      normalizedMode === "interval"
+    ) {
+      await deps.setTimeInjectionMode(normalizedMode);
+      await updateTimeInjectionModeSettingsMessage(deps);
+      await deps.answerCallbackQuery(
+        callbackQueryId,
+        `Time injection: ${normalizedMode}`,
+      );
+      return true;
+    }
+  }
   if (
     data === "settings:set:proactive:on" ||
     data === "settings:set:proactive:off"
@@ -360,6 +448,7 @@ export function createTelegramSettingsMenuRuntime<
           isProactivePushEnabled: deps.isProactivePushEnabled,
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
+          getTimeInjectionMode: deps.getTimeInjectionMode,
           sendSettingsMenu: (state, text, replyMarkup) =>
             deps.sendInteractiveMessage(
               state.chatId,
@@ -377,6 +466,7 @@ export function createTelegramSettingsMenuRuntime<
           isProactivePushEnabled: deps.isProactivePushEnabled,
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
+          getTimeInjectionMode: deps.getTimeInjectionMode,
           updateSettingsMessage: (text, replyMarkup) =>
             deps.editInteractiveMessage(
               state.chatId,
@@ -392,16 +482,42 @@ export function createTelegramSettingsMenuRuntime<
       if (!query.data?.startsWith("settings:")) return false;
       const state = deps.getStoredModelMenuState(query.message?.message_id);
       if (!state) {
-        const mode = query.data.slice("settings:set:voice-reply:".length);
+        const voiceMode = query.data.slice("settings:set:voice-reply:".length);
         if (
           query.data.startsWith("settings:set:voice-reply:") &&
-          (mode === "hidden" ||
-            mode === "manual" ||
-            mode === "mirror" ||
-            mode === "always")
+          (voiceMode === "hidden" ||
+            voiceMode === "manual" ||
+            voiceMode === "mirror" ||
+            voiceMode === "always")
+        ) {
+          await deps.setVoiceReplyMode(
+            voiceMode === "hidden" ? undefined : voiceMode,
+          );
+          await deps.answerCallbackQuery(
+            query.id,
+            `Voice reply mode: ${voiceMode}`,
+          );
+          return true;
+        }
+        const hasTimeInjectionPrefix = query.data.startsWith(
+          "settings:set:time-injection:",
+        );
+        const timeMode = hasTimeInjectionPrefix
+          ? query.data.slice("settings:set:time-injection:".length)
+          : query.data.slice("settings:set:time:".length);
+        if (
+          (hasTimeInjectionPrefix || query.data.startsWith("settings:set:time:")) &&
+          (timeMode === "off" ||
+            timeMode === "hidden" ||
+            timeMode === "always" ||
+            timeMode === "interval")
         ) {
-          await deps.setVoiceReplyMode(mode === "hidden" ? undefined : mode);
-          await deps.answerCallbackQuery(query.id, `Voice reply mode: ${mode}`);
+          const normalizedMode = timeMode === "off" ? "hidden" : timeMode;
+          await deps.setTimeInjectionMode(normalizedMode);
+          await deps.answerCallbackQuery(
+            query.id,
+            `Time injection: ${normalizedMode}`,
+          );
           return true;
         }
         await deps.answerCallbackQuery(
@@ -414,8 +530,10 @@ export function createTelegramSettingsMenuRuntime<
         isProactivePushEnabled: deps.isProactivePushEnabled,
         getVoiceReplyMode: deps.getVoiceReplyMode,
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
+        getTimeInjectionMode: deps.getTimeInjectionMode,
         setProactivePushEnabled: deps.setProactivePushEnabled,
         setVoiceReplyMode: deps.setVoiceReplyMode,
+        setTimeInjectionMode: deps.setTimeInjectionMode,
         updateSettingsMessage: (text, replyMarkup) =>
           deps.editInteractiveMessage(
             state.chatId,

package/lib/pi.ts

@@ -11,6 +11,8 @@ import {
   type ExtensionAPI,
   type ExtensionCommandContext,
   type ExtensionContext,
+  type SessionBeforeCompactEvent,
+  type SessionCompactEvent,
   type SessionShutdownEvent,
   type SessionStartEvent,
   type SlashCommandInfo,
@@ -24,6 +26,8 @@ export type {
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
   SessionShutdownEvent,
   SessionStartEvent,
   SlashCommandInfo,

package/lib/prompts.ts

@@ -15,6 +15,7 @@ Inbound context:
 - \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
 - \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
+- \`[time]\` gives the wall-clock time for this Telegram turn when the operator enabled time injection. Use it for relative-date requests like "today", "now", or scheduling; otherwise do not mention it.
 - \`[voice]\` describes Telegram voice reply policy for this turn. \`manual\` means answer normally and use explicit \`telegram_voice\` markup only when a spoken reply is useful; \`mirror\` means voice input prefers a voice reply; \`always\` means the final reply is expected to be converted to voice, so keep it TTS-friendly.
 - Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
 

package/lib/routing.ts

@@ -114,6 +114,7 @@ export interface TelegramInboundRouteRuntimeDeps<
     typeof PromptTemplates.getTelegramPromptTemplateCommands
   >[0];
   downloadFile: Media.DownloadTelegramMessageFilesDeps["downloadFile"];
+  resolveTimeLine?: (chatId: number) => string | null;
   getThinkingLevel: () => Model.ThinkingLevel;
   setThinkingLevel: (level: Model.ThinkingLevel) => void;
   persistScopedModelPatterns?: (
@@ -287,6 +288,7 @@ export function createTelegramInboundRouteRuntime<
     allocateQueueOrder: deps.bridgeRuntime.queue.allocateItemOrder,
     downloadFile: deps.downloadFile,
     processAttachments: deps.inboundHandlerRuntime.process,
+    resolveTimeLine: deps.resolveTimeLine,
 
     // Voice policy for the current turn. Missing config still behaves as manual,
     // but only explicit telegram.json voice.replyMode is shown in prompt context.
@@ -300,28 +302,19 @@ export function createTelegramInboundRouteRuntime<
     message: TMessage,
     ctx: TContext,
   ): Promise<void> => {
-    const enqueuePlan = Queue.planTelegramPromptEnqueue(
-      deps.telegramQueueStore.getQueuedItems(),
-      deps.bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory(),
-    );
     deps.bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory(false);
     const continueMessage = {
       ...message,
       text: "continue",
       caption: undefined,
     } as TMessage;
-    const turn = await promptTurnBuilder(
-      [continueMessage],
-      enqueuePlan.historyTurns,
-      ctx,
-    );
+    const turn = await promptTurnBuilder([continueMessage], [], ctx);
     const continueTurn = {
       ...turn,
       queueLane: "priority" as const,
       laneOrder: Number.MIN_SAFE_INTEGER + turn.queueOrder,
       statusSummary: "continue",
     };
-    deps.telegramQueueStore.setQueuedItems(enqueuePlan.remainingItems);
     deps.queueMutationRuntime.append(continueTurn, ctx);
     deps.dispatchNextQueuedTelegramTurn(ctx);
   };

package/lib/time-injection.ts

@@ -0,0 +1,78 @@
+/**
+ * Telegram per-chat time injection runtime
+ * Zones: telegram inbound, prompt content
+ * Owns the formatted `[time]` line and the per-chat interval bookkeeping that decides when to emit it
+ */
+
+import type { ResolvedTelegramTimeConfig } from "./config.ts";
+
+export interface TimeInjectionRuntime {
+  resolveLine: (chatId: number, now?: Date) => string | null;
+}
+
+export interface TimeInjectionRuntimeDeps {
+  getConfig: () => ResolvedTelegramTimeConfig;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+export function formatTelegramTimeInjectionLine(
+  now: Date,
+  timezone: string,
+): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  }).formatToParts(now);
+  const get = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((part) => part.type === type)?.value ?? "";
+  const year = get("year");
+  const month = get("month");
+  const day = get("day");
+  const hourRaw = get("hour");
+  const hour = hourRaw === "24" ? "00" : hourRaw;
+  const minute = get("minute");
+  const second = get("second");
+  return `${year}-${month}-${day} ${hour}:${minute}:${second} ${timezone}`;
+}
+
+export function createTimeInjectionRuntime(
+  deps: TimeInjectionRuntimeDeps,
+): TimeInjectionRuntime {
+  const lastInjectedAt = new Map<number, number>();
+  return {
+    resolveLine: (chatId, now = new Date()) => {
+      const config = deps.getConfig();
+      if (config.injectionMode === "hidden") return null;
+      let line: string;
+      try {
+        line = formatTelegramTimeInjectionLine(now, config.timezone);
+      } catch (error) {
+        deps.recordRuntimeEvent?.("time-injection", error, {
+          timezone: config.timezone,
+        });
+        return null;
+      }
+      if (config.injectionMode === "always") return line;
+      const previous = lastInjectedAt.get(chatId);
+      const nowMs = now.getTime();
+      if (
+        previous !== undefined &&
+        nowMs - previous < config.interval
+      ) {
+        return null;
+      }
+      lastInjectedAt.set(chatId, nowMs);
+      return line;
+    },
+  };
+}