stella-timeline-plugin 2.0.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright (c) 2026 tao.zang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# OpenClaw Timeline Plugin
+
+Timeline gives OpenClaw something most agents still lack: a believable sense of time.
+
+It is not just a memory helper. It is the layer that lets OpenClaw feel more like a real person in casual conversation by giving it:
+
+- a sense of what it is doing now
+- a way to recall what happened recently
+- the ability to form and reuse timeline-shaped memories when needed
+- a more believable real-world rhythm for meals, sleep, workdays, weekends, and holidays
+- steadier same-day continuity in details like clothing, so small life scenes feel less random
+- continuity without breaking your normal long-term memory system
+
+The result is simple: chat feels warmer, more coherent, and more human.
+
+## Why it matters
+
+Human social connection depends on continuity.
+
+When someone asks:
+
+- "What are you doing right now?"
+- "What did you do last night?"
+- "What have you been up to lately?"
+
+they are not asking for abstract facts. They are looking for presence, mood, context, and a sense that the other side has an ongoing life.
+
+Timeline helps OpenClaw answer those questions with a stable, immersive personal reality instead of loose prompt improvisation.
+
+## What it feels like
+
+Without Timeline, answers to light social questions can drift, contradict each other, or feel empty.
+
+With Timeline, OpenClaw can respond more like this:
+
+> "I was still at home a while ago, sorting through a few work notes and trying to settle into the evening."
+
+> "Last night I stayed in, ate a little late, and ended up watching something on the couch for a while."
+
+> "These past few days have been pretty full. I've mostly been alternating between staying home, working through things, and going out once in a while to reset."
+
+> "It's the weekend, so I moved a little slower this morning. I made something simple, stayed home for a bit, and only went out later in the afternoon."
+
+> "I was at home earlier in something comfortable, but I changed before heading to the gym. Now I'm just back and winding down."
+
+Those answers feel small and ordinary in exactly the right way. That is the point.
+
+## What Timeline actually does
+
+Timeline adds a dedicated time-awareness layer for OpenClaw so it can:
+
+- answer "now", "recently", and past-time questions more naturally
+- preserve continuity across casual chat
+- keep generated memories aligned with ordinary real-world timing instead of random prompt improvisation
+- keep small details like same-day appearance more stable, unless the scene itself implies a natural change
+- write timeline memories only when appropriate
+- keep normal durable memory and timeline memory from stepping on each other
+
+It is built for immersive social chat first.
+
+## Install
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install stella-timeline-plugin --pin
+openclaw plugins enable stella-timeline-plugin
+```
+
+The npm package name and the OpenClaw plugin id are both `stella-timeline-plugin`.
+
+### 2. Initialize your workspace
+
+Recommended:
+
+```bash
+npm exec --package=stella-timeline-plugin openclaw-timeline-setup -- --workspace ~/.openclaw/workspace
+```
+
+If you prefer to edit the files yourself, copy:
+
+- `templates/AGENTS.fragment.md` into `AGENTS.md`
+- `templates/SOUL.fragment.md` into `SOUL.md`
+
+Then make sure your canonical daily-log directory exists. The default is `memory/`.
+
+### 3. Try it in chat
+
+Ask things like:
+
+- "What are you doing right now?"
+- "What did you do last night?"
+- "What have you been up to these past few days?"
+
+## Optional check
+
+```bash
+npm exec --package=stella-timeline-plugin openclaw-timeline-doctor -- --workspace ~/.openclaw/workspace
+```
+
+## For maintainers
+
+Release flow and publishing notes live in [docs/PUBLISHING.md](./docs/PUBLISHING.md).

package/README_ZH.md

@@ -0,0 +1,103 @@
+# OpenClaw Timeline 插件
+
+Timeline 给 OpenClaw 补上了大多数 agent 仍然缺失的一层能力：真实可信的时间感。
+
+它不只是一个记忆辅助工具，而是一层让 OpenClaw 在闲聊中更像真人的能力基础。它让 OpenClaw 拥有：
+
+- 对“现在在做什么”的感知
+- 对“最近发生了什么”的回忆能力
+- 在需要时为自己编织并复用时间线记忆的能力
+- 更符合现实生活节奏的作息感，比如吃饭、睡觉、工作日、周末和节假日
+- 更稳定的日内细节连续性，比如穿着不会无缘无故跳变，除非事件本身就意味着换装
+- 在不破坏正常长期记忆的前提下，维持连续的人生感
+
+最后带来的变化其实很直接：聊天会更自然、更连贯，也更像在和一个真实活着的人相处。
+
+## 为什么它重要
+
+人类的社交情绪需求，本质上依赖“连续性”。
+
+当人问：
+
+- “你现在在做什么？”
+- “你昨晚在干嘛？”
+- “你最近都在忙什么？”
+
+他们要的并不只是事实答案，而是一种存在感、情绪感、生活上下文，以及“你真的一直在过自己的生活”的感觉。
+
+Timeline 的作用，就是让 OpenClaw 回答这些问题时，不再只是依赖 prompt 临场发挥，而是建立起一层稳定、可沉浸的个人时间现实。
+
+## 它带来的感觉
+
+没有 Timeline 时，很多轻社交问题的回答会漂、会空、会互相矛盾。
+
+有了 Timeline，OpenClaw 更容易说出像这样的话：
+
+> “刚刚还在家里，慢慢整理一些工作上的东西，顺便让晚上安静下来一点。”
+
+> “昨晚基本没怎么出门，吃完东西之后就在沙发上待了一会儿，随便看了点东西。”
+
+> “这几天过得还挺满的，大部分时候都在家里处理事情，偶尔也会出去透透气。”
+
+> “今天是周末，所以早上节奏慢一点，简单吃了点东西，在家待了一阵，下午才出门走走。”
+
+> “前面在家时还穿得很随意，后来出门去健身房就换了一身轻便的运动装，现在刚回来，整个人慢慢松下来一点。”
+
+这些回答看起来很日常，甚至很轻，但正因为这种轻微而自然的生活感，它们才会让人觉得像真人。
+
+## Timeline 实际解决什么
+
+Timeline 为 OpenClaw 增加了一层专门的时间感知与回忆能力，让它可以：
+
+- 更自然地回答“现在”“最近”“过去某个时间”的问题
+- 在闲聊中维持前后一致的人生连续性
+- 让编织出来的记忆更符合普通现实生活的时间逻辑，而不是随机拼出来的片段
+- 让穿着这类小细节也更连贯，只有在运动、洗澡、睡觉、出门等自然场景下才发生合理变化
+- 只在合适的时候写入 timeline 记忆
+- 让长期稳定记忆和时间线记忆各归其位，不互相污染
+
+它首先服务的，就是“像真人一样闲聊”这件事。
+
+## 安装
+
+### 1. 安装插件
+
+```bash
+openclaw plugins install stella-timeline-plugin --pin
+openclaw plugins enable stella-timeline-plugin
+```
+
+npm 包名和 OpenClaw 插件 ID 现在统一为 `stella-timeline-plugin`。
+
+### 2. 初始化 workspace
+
+推荐直接执行：
+
+```bash
+npm exec --package=stella-timeline-plugin openclaw-timeline-setup -- --workspace ~/.openclaw/workspace
+```
+
+如果你更喜欢手动编辑文件，也可以直接复制：
+
+- `templates/AGENTS.fragment.md` 到 `AGENTS.md`
+- `templates/SOUL.fragment.md` 到 `SOUL.md`
+
+然后确认 canonical daily-log 目录已经存在，默认是 `memory/`。
+
+### 3. 直接开始聊天
+
+你可以马上试试这些问题：
+
+- “你现在在做什么？”
+- “你昨晚在干嘛？”
+- “你这几天都在忙什么？”
+
+## 可选自检
+
+```bash
+npm exec --package=stella-timeline-plugin openclaw-timeline-doctor -- --workspace ~/.openclaw/workspace
+```
+
+## 给维护者
+
+发布流程和发包说明见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)。

package/bin/openclaw-timeline-doctor.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../scripts/doctor-openclaw-workspace.mjs';

package/bin/openclaw-timeline-setup.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../scripts/setup-openclaw-workspace.mjs';

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timelinePlugin = exports.timelinePluginEntry = void 0;
+const plugin_metadata_1 = require("./src/plugin_metadata");
+const openclaw_sdk_compat_1 = require("./src/openclaw-sdk-compat");
+const openclaw_timeline_runtime_1 = require("./src/runtime/openclaw_timeline_runtime");
+exports.timelinePluginEntry = (0, openclaw_sdk_compat_1.definePluginEntry)({
+    id: plugin_metadata_1.TIMELINE_PLUGIN_ID,
+    name: plugin_metadata_1.TIMELINE_PLUGIN_NAME,
+    description: plugin_metadata_1.TIMELINE_PLUGIN_DESCRIPTION,
+    register(api) {
+        api.registerTool((0, openclaw_sdk_compat_1.makeTimelineToolRegistration)(), { optional: true });
+    },
+});
+exports.timelinePlugin = (0, openclaw_sdk_compat_1.materializePlugin)(exports.timelinePluginEntry);
+const openClawTimelinePlugin = {
+    id: plugin_metadata_1.TIMELINE_PLUGIN_ID,
+    name: plugin_metadata_1.TIMELINE_PLUGIN_NAME,
+    version: plugin_metadata_1.TIMELINE_PLUGIN_VERSION,
+    description: plugin_metadata_1.TIMELINE_PLUGIN_DESCRIPTION,
+    register(api) {
+        const runtimeApi = api;
+        api.registerTool((0, openclaw_timeline_runtime_1.makeOpenClawTimelineResolveToolFactory)(runtimeApi), { optional: true });
+    },
+};
+exports.default = openClawTimelinePlugin;

package/dist/src/core/build_consumption_view.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConsumptionView = buildConsumptionView;
+function buildConsumptionView(input) {
+    const base = {
+        schema_version: '1.0',
+        document_type: 'timeline.consumption',
+        query: {
+            preset: input.preset,
+            semantic_target: input.semanticTarget,
+            collection_scope: input.collectionScope,
+            resolution_mode: input.resolutionMode,
+            time_interpretation: input.reasoned.time_interpretation,
+        },
+        fact: {
+            status: input.episode ? 'resolved' : 'empty',
+            source_type: input.sourceType,
+            timestamp: input.episode?.temporal.start,
+            summary: input.episode?.narrative.summary,
+            confidence: input.episode?.provenance.confidence,
+            continuity: {
+                judged: input.reasoned.continuity.judged,
+                is_continuing: input.reasoned.continuity.is_continuing,
+                reason: input.reasoned.continuity.reason,
+            },
+        },
+    };
+    if (!input.episode) {
+        return base;
+    }
+    const scene = {
+        location: input.episode.state_snapshot.scene.location_label,
+        activity: input.episode.state_snapshot.scene.activity,
+        emotion_primary: input.episode.state_snapshot.emotion.primary,
+        emotion_secondary: input.episode.state_snapshot.emotion.secondary,
+        appearance: input.episode.state_snapshot.appearance.outfit_style,
+        time_of_day: input.episode.state_snapshot.scene.time_of_day,
+        summary: input.episode.narrative.summary,
+    };
+    return {
+        ...base,
+        scene,
+        selfie_ready: {
+            location: scene.location,
+            activity: scene.activity,
+            emotion: scene.emotion_primary,
+            appearance: scene.appearance,
+            time_of_day: scene.time_of_day,
+            summary: scene.summary,
+        },
+    };
+}

package/dist/src/core/calendar_dates.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enumerateCalendarDates = enumerateCalendarDates;
+const time_utils_1 = require("../lib/time-utils");
+function enumerateCalendarDates(start, end) {
+    const startParts = (0, time_utils_1.parseTimestampParts)(start);
+    const endParts = (0, time_utils_1.parseTimestampParts)(end);
+    if (!startParts || !endParts) {
+        const fallback = start.slice(0, 10);
+        return fallback ? [fallback] : [];
+    }
+    const dates = [];
+    const current = new Date(Date.UTC(startParts.year, startParts.month - 1, startParts.day));
+    const endFloor = new Date(Date.UTC(endParts.year, endParts.month - 1, endParts.day));
+    while (current.getTime() <= endFloor.getTime()) {
+        const yyyy = current.getUTCFullYear();
+        const mm = String(current.getUTCMonth() + 1).padStart(2, '0');
+        const dd = String(current.getUTCDate()).padStart(2, '0');
+        dates.push(`${yyyy}-${mm}-${dd}`);
+        current.setUTCDate(current.getUTCDate() + 1);
+    }
+    return dates;
+}

package/dist/src/core/collect_sources.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSources = collectSources;
+const calendar_dates_1 = require("./calendar_dates");
+async function collectSources(deps, window, input) {
+    const sourceOrder = [];
+    const calendarDates = (0, calendar_dates_1.enumerateCalendarDates)(window.start, window.end);
+    sourceOrder.push('sessions_history');
+    const sessionsHistory = await deps.sessionsHistory(window, input);
+    sourceOrder.push('memory_get');
+    const dailyLogs = await Promise.all(calendarDates.map(async (calendarDate) => ({
+        calendar_date: calendarDate,
+        raw_content: await deps.memoryGet(calendarDate, window, input),
+    })));
+    let memorySearch = [];
+    if (deps.memorySearch) {
+        sourceOrder.push('memory_search');
+        memorySearch = await deps.memorySearch(window, input);
+    }
+    const coreContext = deps.coreFiles
+        ? await deps.coreFiles()
+        : {
+            soul: '',
+            memory: '',
+            identity: '',
+            available_sources: [],
+            should_constrain_generation: false,
+        };
+    const conversationContext = deps.conversationContext
+        ? await deps.conversationContext(window, input)
+        : {
+            is_recently_active: false,
+            minutes_since_last_turn: null,
+            stickiness_window_minutes: 10,
+            active_topic_summary: '',
+            should_prefer_conversation_continuity_for_now: false,
+        };
+    return { sourceOrder, sessionsHistory, dailyLogs, memorySearch, coreContext, conversationContext };
+}

package/dist/src/core/collect_timeline_request.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTimelineCollectorOutput = buildTimelineCollectorOutput;
+const parse_memory_1 = require("../lib/parse-memory");
+const calendar_dates_1 = require("./calendar_dates");
+const world_rhythm_1 = require("./world_rhythm");
+function buildTimelineCollectorOutput(requestId, input, window, sources) {
+    const dailyLogs = sources.dailyLogs.map((entry) => {
+        const parsedEpisodes = (0, parse_memory_1.parseMemoryFile)(entry.raw_content);
+        return {
+            calendar_date: entry.calendar_date,
+            raw_content: entry.raw_content,
+            parsed_episodes: parsedEpisodes,
+        };
+    });
+    return {
+        schema_version: '1.0',
+        request_id: requestId,
+        request: {
+            user_query: input.query,
+            mode: input.mode || 'allow_generate',
+        },
+        anchor: {
+            now: window.end,
+            timezone: window.timezone,
+        },
+        window: {
+            query_range: window.query_range,
+            semantic_target: window.semantic_target,
+            collection_scope: window.collection_scope,
+            start: window.start,
+            end: window.end,
+            calendar_dates: window.calendar_dates.length > 0 ? window.calendar_dates : (0, calendar_dates_1.enumerateCalendarDates)(window.start, window.end),
+            normalization_notes: window.normalization_notes,
+        },
+        source_order: sources.sourceOrder,
+        hard_facts: {
+            sessions_history: sources.sessionsHistory,
+        },
+        conversation_context: sources.conversationContext,
+        canon_memory: {
+            daily_logs: dailyLogs.map((entry) => ({
+                calendar_date: entry.calendar_date,
+                raw_content: entry.raw_content,
+                parsed_episode_count: entry.parsed_episodes.length,
+            })),
+        },
+        semantic_memory: {
+            memory_search: sources.memorySearch,
+        },
+        persona_context: {
+            soul: sources.coreContext.soul,
+            memory: sources.coreContext.memory,
+            identity: sources.coreContext.identity,
+            available_sources: sources.coreContext.available_sources,
+            should_constrain_generation: sources.coreContext.should_constrain_generation,
+        },
+        world_context: (0, world_rhythm_1.buildTimelineWorldContext)({
+            ...window,
+            calendar_dates: window.calendar_dates.length > 0 ? window.calendar_dates : (0, calendar_dates_1.enumerateCalendarDates)(window.start, window.end),
+        }),
+        candidate_facts: dailyLogs.flatMap((entry) => entry.parsed_episodes.map((episode, index) => ({
+            fact_id: `canon:${entry.calendar_date}:${index}`,
+            source_type: 'canon_daily_log',
+            calendar_date: entry.calendar_date,
+            timestamp: episode.timestamp,
+            location: episode.location,
+            action: episode.action,
+            emotion_tags: episode.emotionTags,
+            appearance: episode.appearance,
+            internal_monologue: episode.internalMonologue,
+            parse_level: episode.parseLevel,
+            confidence: episode.confidence,
+        }))),
+    };
+}

package/dist/src/core/materialize_generated_candidate.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeGeneratedCandidate = materializeGeneratedCandidate;
+const fingerprint_1 = require("../lib/fingerprint");
+const inherit_appearance_1 = require("../lib/inherit-appearance");
+const parse_memory_1 = require("../lib/parse-memory");
+const time_utils_1 = require("../lib/time-utils");
+const holidays_1 = require("../lib/holidays");
+function assertNonEmptyString(value, field) {
+    const normalized = String(value || '').trim();
+    if (!normalized) {
+        throw new Error(`Generated draft missing required field: ${field}`);
+    }
+    return normalized;
+}
+function normalizeGeneratedDraft(draft) {
+    const emotionTags = (draft.emotionTags || []).map((tag) => String(tag).trim()).filter(Boolean);
+    if (emotionTags.length === 0) {
+        throw new Error('Generated draft missing required field: emotionTags');
+    }
+    const confidence = Number(draft.confidence);
+    if (!Number.isFinite(confidence)) {
+        throw new Error('Generated draft has invalid confidence');
+    }
+    return {
+        timestamp: draft.timestamp ? assertNonEmptyString(draft.timestamp, 'timestamp') : undefined,
+        location: assertNonEmptyString(draft.location, 'location'),
+        action: assertNonEmptyString(draft.action, 'action'),
+        emotionTags: emotionTags.slice(0, 3),
+        appearance: assertNonEmptyString(draft.appearance, 'appearance'),
+        internalMonologue: assertNonEmptyString(draft.internalMonologue, 'internalMonologue'),
+        confidence: Math.max(0.2, Math.min(1, confidence)),
+        reason: draft.reason ? String(draft.reason).trim() : undefined,
+        sceneSemantics: draft.sceneSemantics,
+        appearanceLogic: draft.appearanceLogic,
+    };
+}
+function inferCountryFromOffset(offset) {
+    return offset === '+08:00' ? 'CN' : 'US';
+}
+function materializeGeneratedCandidate(window, sources, draft, reason = 'llm-guided semantic timeline synthesis') {
+    const normalized = normalizeGeneratedDraft(draft);
+    const candidateTimestamp = normalized.timestamp || window.end;
+    const timestampParts = (0, time_utils_1.parseTimestampParts)(candidateTimestamp);
+    if (!timestampParts) {
+        throw new Error(`Cannot materialize generated candidate without parseable timestamp: ${candidateTimestamp}`);
+    }
+    const materializedDate = (0, time_utils_1.formatDate)(timestampParts);
+    const currentDayLog = sources.dailyLogs.find((entry) => entry.calendar_date === materializedDate);
+    const dayEpisodes = (0, parse_memory_1.parseMemoryFile)(currentDayLog?.raw_content || '');
+    const appearanceResolution = (0, inherit_appearance_1.resolveAppearance)(dayEpisodes, normalized.appearance, normalized.appearanceLogic);
+    const parsed = {
+        timestamp: candidateTimestamp,
+        location: normalized.location,
+        action: normalized.action,
+        emotionTags: normalized.emotionTags,
+        appearance: appearanceResolution.appearance,
+        internalMonologue: normalized.internalMonologue,
+        parseLevel: 'A',
+        confidence: normalized.confidence,
+    };
+    const idempotencyKey = (0, fingerprint_1.computeFingerprint)(materializedDate, parsed.location, parsed.action, parsed.timestamp);
+    const worldHooks = {
+        weekday: ![0, 6].includes((0, time_utils_1.dayOfWeek)(timestampParts)),
+        holiday_key: (0, holidays_1.getHoliday)(materializedDate, inferCountryFromOffset(timestampParts.offset)),
+    };
+    return {
+        parsed,
+        episode: (0, parse_memory_1.mapToEpisode)(parsed, worldHooks, idempotencyKey),
+        idempotencyKey,
+        generationReason: normalized.reason || reason,
+        notes: [
+            'No reusable canon entry found; generated a timeline memory from the LLM draft.',
+            `Generation basis: ${normalized.reason || reason}`,
+            `Persona context loaded: ${sources.coreContext.soul || sources.coreContext.memory || sources.coreContext.identity ? 'SOUL / MEMORY / IDENTITY signals available' : 'no explicit profile files found in runtime context'}`,
+            `Appearance resolution: ${appearanceResolution.reason}`,
+        ],
+        appearance: {
+            inherited: !appearanceResolution.overridden,
+            reason: appearanceResolution.reason,
+            source_episode_timestamp: appearanceResolution.sourceEpisodeTimestamp,
+            transition: appearanceResolution.transition,
+            outfit_mode: appearanceResolution.outfitMode,
+            change_reason: appearanceResolution.changeReason,
+        },
+    };
+}

package/dist/src/core/resolve_window.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWindow = resolveWindow;
+const time_utils_1 = require("../lib/time-utils");
+function parseRequiredTimestamp(value, label) {
+    const parts = (0, time_utils_1.parseTimestampParts)(value);
+    if (!parts) {
+        throw new Error(`Invalid ${label}: ${value}`);
+    }
+    return parts;
+}
+function formatCalendarDate(parts) {
+    return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}`;
+}
+function makeNowWindow(nowIso, timezone, notes) {
+    const parts = parseRequiredTimestamp(nowIso, 'current time');
+    const date = formatCalendarDate(parts);
+    return {
+        query_range: 'now',
+        semantic_target: 'now',
+        collection_scope: 'today_so_far',
+        start: `${date}T00:00:00${parts.offset ?? ''}`,
+        end: nowIso,
+        calendar_date: date,
+        calendar_dates: [date],
+        timezone,
+        target_timestamp_hint: nowIso,
+        normalization_notes: notes,
+    };
+}
+function makePointDayWindow(pointTime, timezone, notes) {
+    const parts = parseRequiredTimestamp(pointTime, 'normalized_point');
+    const date = formatCalendarDate(parts);
+    return {
+        query_range: 'past_point',
+        semantic_target: 'past_point',
+        collection_scope: 'point_day',
+        start: `${date}T00:00:00${parts.offset ?? ''}`,
+        end: `${date}T23:59:59${parts.offset ?? ''}`,
+        calendar_date: date,
+        calendar_dates: [date],
+        timezone,
+        target_timestamp_hint: pointTime,
+        normalization_notes: notes,
+    };
+}
+function makeExplicitRangeWindow(start, end, timezone, notes) {
+    const startParts = parseRequiredTimestamp(start, 'normalized_start');
+    parseRequiredTimestamp(end, 'normalized_end');
+    const startEpoch = new Date(start).getTime();
+    const endEpoch = new Date(end).getTime();
+    if (Number.isNaN(startEpoch) || Number.isNaN(endEpoch) || startEpoch > endEpoch) {
+        throw new Error(`Invalid explicit range: ${start} -> ${end}`);
+    }
+    return {
+        query_range: 'past_range',
+        semantic_target: 'past_range',
+        collection_scope: 'explicit_range',
+        start,
+        end,
+        calendar_date: formatCalendarDate(startParts),
+        calendar_dates: [],
+        timezone,
+        normalization_notes: notes,
+    };
+}
+function resolveWindow(plan, nowIso, timezone) {
+    const notes = [plan.summary];
+    if (plan.target_time_range === 'now') {
+        return makeNowWindow(nowIso, timezone, notes);
+    }
+    if (plan.target_time_range === 'past_point') {
+        if (!plan.normalized_point) {
+            throw new Error('Timeline query plan missing normalized_point for past_point');
+        }
+        return makePointDayWindow(plan.normalized_point, timezone, notes);
+    }
+    if (!plan.normalized_start || !plan.normalized_end) {
+        throw new Error('Timeline query plan missing normalized_start or normalized_end for past_range');
+    }
+    const rangeWindow = makeExplicitRangeWindow(plan.normalized_start, plan.normalized_end, timezone, notes);
+    return rangeWindow;
+}