@llblab/pi-telegram 0.11.0 → 0.11.1

package/AGENTS.md

@@ -73,7 +73,8 @@
 - Telegram delivery strips top-level HTML comments from preview/final text; column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks are special outbound comments handled after `agent_end` without requiring agent-side transport tool calls, while comments inside code, quotes, lists, or indented examples stay literal
 - `telegram_voice` and `telegram_button` are not π tools; keep prompts/docs explicit that agents should author markup while voice synthesis provider extensions own TTS/OGG conversion, and pi-telegram owns button routing plus Telegram delivery
 - Voice reply policy and prompt context are owned by pi-telegram's `telegram.json` `voice.replyMode`: missing/invalid config behaves as `manual` but does not add a `[voice]` prompt-context block; only an explicit valid `voice.replyMode` renders context. Render a single voice field as `[voice] reply mode: manual|mirror|always`, and render multiple fields as a `[voice]` list; place voice context after `[outputs]` when handler output exists, otherwise after `[attachments]`; provider prompt contributions are optional provider-specific additions, not the default policy channel
-- Voice reply mode Settings UI standard: the top-level Settings row is `👄 Voice reply: hidden|manual|mirror|always`; `hidden` is the true default and means no valid `voice.replyMode` is persisted, behavior is manual, and no voice policy is added to prompt context; explicit `manual` behaves the same operationally but renders reply-mode context. The submenu title is `Voice reply mode:`; choice buttons use lowercase labels with a model-style active dot (`🟢 hidden`, `🟢 mirror`) rather than per-mode emoji; the explanatory submenu body uses compact HTML-code bullets such as `<code>-</code> <code>hidden</code> (default): ...`. Preserve this wording/icons unless the operator explicitly asks to redesign it
+- Optional `telegram.json` `time` may add `[time] YYYY-MM-DD HH:mm:ss <timezone>` to Telegram-originated prompts for wall-clock context. It is off by default, uses `time.injectionMode` values `off|always|interval`, stores `time.interval` in milliseconds, uses the system timezone, and should render last after `[attachments]`, `[outputs]`, and `[voice]` sections. The Settings row `🕒 Time injection: off|always|interval` controls `time.injectionMode` only.
+- Voice reply mode Settings UI standard: the top-level Settings row is `👄 Voice reply: hidden|manual|mirror|always`; `hidden` is the true default and means no valid `voice.replyMode` is persisted, behavior is manual, and no voice policy is added to prompt context; explicit `manual` behaves the same operationally but renders reply-mode context. The submenu title is `👄 Voice reply mode:`; choice buttons use lowercase labels with a model-style active dot (`🟢 hidden`, `🟢 mirror`) rather than per-mode emoji; the explanatory submenu body uses compact HTML-code bullets such as `<code>-</code> <code>hidden</code> (default): ...`. Preserve this wording/icons unless the operator explicitly asks to redesign it
 - Outbound voice delivery is one fallback pipeline: configured `outboundHandlers` with `type: "voice"` run first in `telegram.json` order, then programmatic voice handlers, then registered voice synthesis providers as zero-config progressive fallbacks; provider extensions must not override operator-configured handlers
 - `telegram_voice` text is arbitrary TTS-target text: use body form for multiline text, `<!-- telegram_voice text="Short summary" -->` for explicit one-line text, or `<!-- telegram_voice: Short summary -->` for one-line text with no attributes
 - `telegram_button` has three canonical forms: `<!-- telegram_button: OK -->` for label-only buttons, `<!-- telegram_button label=Continue prompt="Continue with the current plan." -->` for one-line prompts, or `<!-- telegram_button label="Show risks"\nList the main risks first.\n-->` for multiline prompts
@@ -128,7 +129,7 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - When durable runtime constraints or repeat bug patterns emerge, record them here instead of burying them in changelog prose
 - When fork identity changes, keep `README.md`, package metadata, and docs aligned so the published package does not point back at stale upstream coordinates
 - README positioning should emphasize `/start` as the primary Telegram operator menu and keep reaction shortcuts secondary. Reactions are useful queue affordances, but menu controls are the core CLI-to-Telegram bridge.
-- Document configuration knobs without UI in the root README when they affect bootstrap, networking, or transport limits; currently this includes token env bootstrap, Node env proxy mode, and inbound/outbound size limits.
+- Document configuration knobs without UI in the root README when they affect bootstrap, networking, transport limits, or prompt context; currently this includes token env bootstrap, Node env proxy mode, inbound/outbound size limits, and `time`.
 - Work only inside this repository during development tasks; updating the installed Pi extension checkout is a separate manual operator step, not part of normal in-repo implementation work
 
 ## 8. Integration Protocols

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+## 0.11.1: Time Context And Settings Polish
+
+- `[Time Context]` Added optional `telegram.json` `time` prompt context for Telegram-originated turns. `time.injectionMode` values are `off`, `always`, and per-chat `interval`; `time.interval` is stored in milliseconds and timezone comes from the system. The `[time]` line renders last after attachments, handler outputs, and voice context, and Settings exposes a `🕒 Time` mode selector.
+- `[Settings UI]` The proactive push row now uses `📌 Proactive push: on|off`, and proactive push, time, and voice reply submenus use matching emoji headings.
+
 ## 0.11.0: Voice Provider Platform
 
 - `[Voice Synthesis Provider API]` Added a first-class voice synthesis provider surface for Telegram voice replies. Providers register with `registerTelegramVoiceSynthesisProvider()` from `@llblab/pi-telegram/lib/voice.ts`, synthesize text into `.ogg`/`.opus`, may return `{ audioPath, transcriptText }`, and can contribute voice-specific prompt guidance through `getVoicePromptContribution(view)`.

package/README.md

@@ -238,6 +238,21 @@ Import `registerTelegramSection()` from `@llblab/pi-telegram/lib/extension-secti
 
 `telegram.json` can set `proactivePush: true` to send successful local non-Telegram final replies to the paired Telegram chat when no Telegram turn is active. Local prompt text is not mirrored because the bot does not own terminal user messages. The mode is off by default and can be toggled from settings.
 
+### Time context
+
+`telegram.json` can opt into a compact `[time]` line in Telegram-originated prompts so π has a wall-clock reference for requests such as "today", "now", or scheduling. It is off by default and uses the system timezone; the mode can also be changed from Settings → `🕒 Time`.
+
+```json
+{
+  "time": {
+    "injectionMode": "interval",
+    "interval": 3600000
+  }
+}
+```
+
+Modes are `off`, `always`, and `interval`. `interval` is measured in milliseconds and rate-limits the time line per chat in memory, so back-to-back messages do not repeatedly spend context on the same timestamp. When present, `[time]` is the final prompt-context section after attachments, handler outputs, and voice policy.
+
 ## Docs
 
 - [Project Context](./AGENTS.md): durable engineering conventions and architecture constraints.

package/docs/architecture.md

@@ -28,7 +28,7 @@ Current runtime areas use these ownership boundaries:
 - `config` / `setup`: persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, and config persistence.
 - `locks` / `polling`: singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, and poll-loop runtime wiring.
 - `updates` / `routing`: update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition.
-- `media` / `text-groups` / `turns` / `inbound-handlers`: text/media extraction, media-group debounce, long-text split coalescing, inbound downloads, configured and programmatic inbound text/media handler execution, turn building/editing, image reads, and legacy `attachmentHandlers` compatibility.
+- `media` / `text-groups` / `time-injection` / `turns` / `inbound-handlers`: text/media extraction, media-group debounce, long-text split coalescing, optional per-chat wall-clock prompt context, inbound downloads, configured and programmatic inbound text/media handler execution, turn building/editing, image reads, and legacy `attachmentHandlers` compatibility.
 - `queue`: queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, and session/agent/tool lifecycle sequencing.
 - `runtime`: session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, and agent-end reset binding.
 - `model` / `menu-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `menu-settings` / `commands`: model identity/thinking levels, scoped model resolution, in-flight switching, model/thinking/status/queue/settings menu UI, inline application callback composition, slash commands, and bot command registration.
@@ -79,9 +79,10 @@ Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runti
 7. Configured inbound handlers may run on raw text or downloaded files by MIME wildcard, Telegram attachment type, or generic match selector; command templates receive safe command-arg substitution for `{text}`, `{file}`, `{mime}`, and `{type}` where applicable
 8. Matching media/file handlers are tried in config order: a non-zero exit records diagnostics and falls back to the next matching handler, while the first successful handler stops the chain
 9. Local attachments stay visible under `[attachments] <directory>` with relative file entries, and handler stdout is appended under `[outputs]` before the agent sees the turn; failed handlers omit output while keeping the attachment entry
-10. A `PendingTelegramTurn` is created and queued locally
-11. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
-12. The queue dispatcher sends the turn into π only when dispatch is safe
+10. Optional `time` config may add a compact final `[time]` prompt line after attachment/output/voice sections, either every turn or per-chat after the configured millisecond interval, using the system timezone
+11. A `PendingTelegramTurn` is created and queued locally
+12. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
+13. The queue dispatcher sends the turn into π only when dispatch is safe
 
 ### Queue Safety Model
 
@@ -114,7 +115,7 @@ Dispatch is gated by:
 
 This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/start` and hidden compatibility shortcuts `/status`, `/model`, `/thinking`, `/queue`, and `/settings` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
 
-`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The `Status` row reports `compacting` while a Telegram `/compact` run is active, and the bridge sends Telegram's native `typing` chat action as a keepalive for the same compaction window. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens, while `/settings` opens the hidden settings menu for bridge toggles such as proactive push. Settings options open detail submenus; checkbox-like settings use Back plus green/black/yellow `on` and `off` controls instead of mutating directly from the list. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, stay visible only inside the `/start` menu, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu pagination controls sit near the top, tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`, and tapping a model opens a detail submenu with Back, ☑️ Activate/🟢 Active selection, and yellow/black-marked Scoped/All membership tabs. `menu-model` owns model-menu state, scoped model pages, model detail rendering, scoped-list persistence planning, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text with the bottom-filled `⌛` hourglass plus the top Main menu button, while non-empty queue states keep the running `⏳` hourglass. Selecting an item opens a submenu that displays the queue item number above the full queued prompt text with Back, side-by-side Priority/Normal tabs, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
+`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The `Status` row reports `compacting` while a Telegram `/compact` run is active, and the bridge sends Telegram's native `typing` chat action as a keepalive for the same compaction window. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens, while `/settings` opens the hidden settings menu for bridge toggles such as proactive push, voice reply mode, and `time.injectionMode`. Settings options open detail submenus; checkbox-like settings use Back plus green/black/yellow `on` and `off` controls instead of mutating directly from the list. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, stay visible only inside the `/start` menu, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu pagination controls sit near the top, tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`, and tapping a model opens a detail submenu with Back, ☑️ Activate/🟢 Active selection, and yellow/black-marked Scoped/All membership tabs. `menu-model` owns model-menu state, scoped model pages, model detail rendering, scoped-list persistence planning, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text with the bottom-filled `⌛` hourglass plus the top Main menu button, while non-empty queue states keep the running `⏳` hourglass. Selecting an item opens a submenu that displays the queue item number above the full queued prompt text with Back, side-by-side Priority/Normal tabs, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
 
 ### Abort Behavior
 

package/index.ts

@@ -38,6 +38,7 @@ import * as Runtime from "./lib/runtime.ts";
 import * as Setup from "./lib/setup.ts";
 import * as Status from "./lib/status.ts";
 import * as TextGroups from "./lib/text-groups.ts";
+import * as TimeInjection from "./lib/time-injection.ts";
 import * as Voice from "./lib/voice.ts";
 
 const VOICE_EVENT_RECORDER_KEY = "__piTelegramVoiceEventRecorder__";
@@ -113,6 +114,10 @@ export default function (pi: Pi.ExtensionAPI) {
     Config.createTelegramVoiceReplyModeConfiguredChecker(configStore);
   const setVoiceReplyMode =
     Config.createTelegramVoiceReplyModeSetter(configStore);
+  const getTimeInjectionMode =
+    Config.createTelegramTimeInjectionModeGetter(configStore);
+  const setTimeInjectionMode =
+    Config.createTelegramTimeInjectionModeSetter(configStore);
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
@@ -137,6 +142,10 @@ export default function (pi: Pi.ExtensionAPI) {
     getBotToken: configStore.getBotToken,
   });
   const recordRuntimeEvent = runtimeEvents.record;
+  const timeInjectionRuntime = TimeInjection.createTimeInjectionRuntime({
+    getConfig: Config.createTelegramTimeConfigGetter(configStore),
+    recordRuntimeEvent,
+  });
   (globalThis as Record<string, unknown>)[
     VOICE_EVENT_RECORDER_KEY
   ] = recordRuntimeEvent;
@@ -386,8 +395,10 @@ export default function (pi: Pi.ExtensionAPI) {
       isProactivePushEnabled,
       getVoiceReplyMode,
       isVoiceReplyModeConfigured,
+      getTimeInjectionMode,
       setProactivePushEnabled,
       setVoiceReplyMode,
+      setTimeInjectionMode,
     },
     sectionRegistry,
   );
@@ -435,6 +446,7 @@ export default function (pi: Pi.ExtensionAPI) {
     setMyCommands,
     getCommands,
     downloadFile: downloadTelegramBridgeFile,
+    resolveTimeLine: timeInjectionRuntime.resolveLine,
     getThinkingLevel,
     setThinkingLevel,
     persistScopedModelPatterns: Pi.createScopedModelPatternPersister({

package/lib/config.ts

@@ -35,6 +35,19 @@ export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConf
   timeout?: number;
 }
 
+export type TelegramTimeMode = "off" | "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
+      : "off";
+  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/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";
 
@@ -152,9 +156,22 @@ export function buildVoiceReplyModeSettingsText(): string {
   ].join("\n");
 }
 
+export function buildTimeInjectionModeSettingsText(): string {
+  return [
+    TIME_INJECTION_MODE_SETTINGS_TITLE,
+    "",
+    "Controls whether Telegram-originated prompts include a compact wall-clock [time] line.",
+    "",
+    "<code>-</code> <code>off</code> (default): no time line is added.",
+    "<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 +196,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 +223,7 @@ export async function openTelegramSettingsMenu<
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
       deps.getVoiceReplyMode(),
+      deps.getTimeInjectionMode(),
       sectionRegistry,
       deps.isVoiceReplyModeConfigured(),
     ),
@@ -230,6 +254,23 @@ export function buildProactivePushSettingsReplyMarkup(
   };
 }
 
+export function buildTimeInjectionModeSettingsReplyMarkup(
+  mode: TelegramTimeMode,
+): TelegramSettingsMenuReplyMarkup {
+  const modes: TelegramTimeMode[] = ["off", "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 +304,7 @@ export async function updateTelegramSettingsMenuMessage(
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
       deps.getVoiceReplyMode(),
+      deps.getTimeInjectionMode(),
       sectionRegistry,
       deps.isVoiceReplyModeConfigured(),
     ),
@@ -278,6 +320,15 @@ export async function updateProactivePushSettingsMessage(
   );
 }
 
+export async function updateTimeInjectionModeSettingsMessage(
+  deps: TelegramSettingsMenuCallbackDeps,
+): Promise<void> {
+  await deps.updateSettingsMessage(
+    buildTimeInjectionModeSettingsText(),
+    buildTimeInjectionModeSettingsReplyMarkup(deps.getTimeInjectionMode()),
+  );
+}
+
 export async function updateVoiceReplyModeSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
@@ -311,6 +362,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 +384,20 @@ 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);
+    if (mode === "off" || mode === "always" || mode === "interval") {
+      await deps.setTimeInjectionMode(mode);
+      await updateTimeInjectionModeSettingsMessage(deps);
+      await deps.answerCallbackQuery(callbackQueryId, `Time injection: ${mode}`);
+      return true;
+    }
+  }
   if (
     data === "settings:set:proactive:on" ||
     data === "settings:set:proactive:off"
@@ -360,6 +430,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 +448,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 +464,40 @@ 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 === "always" ||
+            timeMode === "interval")
         ) {
-          await deps.setVoiceReplyMode(mode === "hidden" ? undefined : mode);
-          await deps.answerCallbackQuery(query.id, `Voice reply mode: ${mode}`);
+          await deps.setTimeInjectionMode(timeMode);
+          await deps.answerCallbackQuery(
+            query.id,
+            `Time injection: ${timeMode}`,
+          );
           return true;
         }
         await deps.answerCallbackQuery(
@@ -414,8 +510,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/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.

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 === "off") 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;
+    },
+  };
+}

package/lib/turns.ts

@@ -127,6 +127,7 @@ export function buildTelegramTurnPrompt(options: {
   promptFiles?: DownloadedTelegramTurnFile[];
   handlerOutputs?: string[];
   historyTurns?: Pick<PendingTelegramTurn, "historyText">[];
+  timeLine?: string | null;
   voiceContext?: Record<string, string>;
 }): string {
   let prompt = options.telegramPrefix;
@@ -154,6 +155,9 @@ export function buildTelegramTurnPrompt(options: {
   if (options.voiceContext) {
     prompt = appendTelegramVoiceContext(prompt, options.voiceContext);
   }
+  if (options.timeLine) {
+    prompt = `${prompt}\n\n[time] ${options.timeLine}`;
+  }
   return prompt;
 }
 
@@ -330,6 +334,7 @@ export interface BuildTelegramPromptTurnOptions {
   files: DownloadedTelegramTurnFile[];
   promptFiles?: DownloadedTelegramTurnFile[];
   handlerOutputs?: string[];
+  timeLine?: string | null;
   readBinaryFile: (path: string) => Promise<Uint8Array>;
   inferImageMimeType: (path: string) => string | undefined;
   voiceReplyMode?: TelegramVoiceReplyMode;
@@ -355,6 +360,7 @@ export interface TelegramPromptTurnRuntimeBuilderDeps<
     promptFiles?: DownloadedTelegramTurnFile[];
     handlerOutputs?: string[];
   }>;
+  resolveTimeLine?: (chatId: number) => string | null;
   getVoiceReplyMode?: () => TelegramVoiceReplyMode;
   isVoiceReplyModeConfigured?: () => boolean;
 }
@@ -386,6 +392,11 @@ export function createTelegramPromptTurnRuntimeBuilder<
     );
     // Compute voice mode once and pass it to both the turn builder and the prompt contribution helper
     const voiceReplyMode = deps.getVoiceReplyMode?.();
+    const chatId = messages[0]?.chat.id;
+    const timeLine =
+      deps.resolveTimeLine && chatId !== undefined
+        ? deps.resolveTimeLine(chatId)
+        : null;
     return buildTelegramPromptTurnRuntime({
       telegramPrefix: TELEGRAM_PREFIX,
       messages,
@@ -396,6 +407,7 @@ export function createTelegramPromptTurnRuntimeBuilder<
       files,
       promptFiles: processed.promptFiles,
       handlerOutputs: processed.handlerOutputs,
+      timeLine,
       inferImageMimeType: guessMediaType,
       voiceReplyMode,
       voiceReplyModeConfigured: deps.isVoiceReplyModeConfigured?.(),
@@ -440,6 +452,7 @@ export async function buildTelegramPromptTurn(
         promptFiles: options.promptFiles,
         handlerOutputs: options.handlerOutputs,
         historyTurns: options.historyTurns,
+        timeLine: options.timeLine,
         voiceContext: showVoiceContext
           ? getTelegramVoicePromptContext(voiceReplyMode, hasVoiceFile)
           : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": false,
   "publishConfig": {
     "access": "public"