stella-timeline-plugin 2.0.0

package/dist/src/tools/timeline_resolve.js

@@ -0,0 +1,689 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timelineResolveToolSpec = void 0;
+exports.setTimelineResolveDependencies = setTimelineResolveDependencies;
+exports.resetTimelineResolveDependencies = resetTimelineResolveDependencies;
+exports.timelineResolve = timelineResolve;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const collect_sources_1 = require("../core/collect_sources");
+const collect_timeline_request_1 = require("../core/collect_timeline_request");
+const materialize_generated_candidate_1 = require("../core/materialize_generated_candidate");
+const runtime_guard_1 = require("../core/runtime_guard");
+const trace_1 = require("../core/trace");
+const build_consumption_view_1 = require("../core/build_consumption_view");
+const parse_memory_1 = require("../lib/parse-memory");
+const fingerprint_1 = require("../lib/fingerprint");
+const time_utils_1 = require("../lib/time-utils");
+const holidays_1 = require("../lib/holidays");
+const daily_log_1 = require("../storage/daily_log");
+const lock_1 = require("../storage/lock");
+const trace_log_1 = require("../storage/trace_log");
+const write_episode_1 = require("../storage/write-episode");
+const resolve_window_1 = require("../core/resolve_window");
+function readOptionalTextFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+const defaultDependencies = {
+    currentTime: async () => ({
+        now: new Date().toISOString(),
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
+    }),
+    sessionsHistory: async () => [],
+    memoryGet: async () => '',
+    memorySearch: async () => [],
+    coreFiles: async () => ({
+        soul: readOptionalTextFile(path.join(process.cwd(), 'SOUL.md')),
+        memory: readOptionalTextFile(path.join(process.cwd(), 'MEMORY.md')) || readOptionalTextFile(path.join(process.cwd(), 'memory.md')),
+        identity: readOptionalTextFile(path.join(process.cwd(), 'IDENTITY.md')) || readOptionalTextFile(path.join(process.cwd(), 'IDENTITY')),
+        available_sources: [
+            readOptionalTextFile(path.join(process.cwd(), 'SOUL.md')).trim() ? 'soul' : '',
+            (readOptionalTextFile(path.join(process.cwd(), 'MEMORY.md')) || readOptionalTextFile(path.join(process.cwd(), 'memory.md'))).trim() ? 'memory' : '',
+            (readOptionalTextFile(path.join(process.cwd(), 'IDENTITY.md')) || readOptionalTextFile(path.join(process.cwd(), 'IDENTITY'))).trim() ? 'identity' : '',
+        ].filter(Boolean),
+        should_constrain_generation: Boolean(readOptionalTextFile(path.join(process.cwd(), 'SOUL.md')).trim()
+            || (readOptionalTextFile(path.join(process.cwd(), 'MEMORY.md')) || readOptionalTextFile(path.join(process.cwd(), 'memory.md'))).trim()
+            || (readOptionalTextFile(path.join(process.cwd(), 'IDENTITY.md')) || readOptionalTextFile(path.join(process.cwd(), 'IDENTITY'))).trim()),
+    }),
+    writeEpisode: write_episode_1.writeEpisode,
+    memoryFilePath: (calendarDate) => `memory/${calendarDate}.md`,
+    canonicalRootName: 'memory',
+    traceLogPath: path.join(os.tmpdir(), 'stella-timeline-plugin-trace.log'),
+};
+let runtimeDependencies = defaultDependencies;
+function setTimelineResolveDependencies(deps) {
+    runtimeDependencies = { ...runtimeDependencies, ...deps };
+}
+function resetTimelineResolveDependencies() {
+    runtimeDependencies = defaultDependencies;
+}
+function getEffectiveTimelineDependencies(overrides) {
+    return {
+        ...runtimeDependencies,
+        ...overrides,
+    };
+}
+function validateTimelineResolveInput(input) {
+    if (!String(input.query || '').trim()) {
+        throw new Error('timeline_resolve requires query');
+    }
+}
+function classifyTimelineResolveError(error) {
+    const message = error.message || 'Unknown timeline_resolve failure';
+    if (message.includes('timeline_resolve requires query')) {
+        return 'INVALID_INPUT';
+    }
+    if (message.includes('Invalid explicit range')
+        || message.includes('normalized_point')
+        || message.includes('normalized_start')
+        || message.includes('normalized_end')) {
+        return 'INVALID_RANGE';
+    }
+    if (message.includes('Timeline reasoner dependency missing')
+        || message.includes('Timeline reasoner returned no decision')
+        || message.includes('Timeline query planner dependency missing')
+        || message.includes('Timeline query planner returned no decision')) {
+        return 'REASONER_UNAVAILABLE';
+    }
+    if (message.includes('LLM generation'))
+        return 'GENERATION_UNAVAILABLE';
+    if (message.includes('Generated draft'))
+        return 'GENERATION_UNAVAILABLE';
+    if (message.includes('Invalid reasoner output'))
+        return 'INVALID_REASONER_OUTPUT';
+    if (message.includes('Canonical daily logs'))
+        return 'WRITE_BLOCKED';
+    if (message.includes('Lock already held'))
+        return 'WRITE_CONFLICT';
+    if (message.includes('write dependency missing'))
+        return 'WRITE_BLOCKED';
+    if (message.includes('parse'))
+        return 'PARSE_ERROR';
+    if (message.includes('sessions_history') || message.includes('memory_get') || message.includes('memory_search')) {
+        return 'SOURCE_FAILURE';
+    }
+    return 'INTERNAL';
+}
+function normalizeMode(mode) {
+    return mode || 'allow_generate';
+}
+function classifyWriteFailure(writeResult) {
+    if (writeResult.error_code === 'CONFLICT_EXISTS') {
+        return {
+            mode: 'write_conflict',
+            errorCode: 'WRITE_CONFLICT',
+            guard: 'conflict',
+            recoveryHint: writeResult.recovery_hint,
+        };
+    }
+    if (writeResult.error_code === 'LOCK_EXISTS') {
+        return {
+            mode: 'write_conflict',
+            errorCode: 'WRITE_CONFLICT',
+            guard: 'lock',
+            recoveryHint: writeResult.recovery_hint ?? 'Retry once the current timeline writer releases the file lock.',
+        };
+    }
+    if (writeResult.error === 'write dependency missing') {
+        return {
+            mode: 'write_blocked',
+            errorCode: 'WRITE_BLOCKED',
+            guard: 'write_dependency',
+            recoveryHint: 'Configure the timeline writer dependencies before allowing generated writes.',
+        };
+    }
+    if ((writeResult.error || '').includes('Canonical daily logs')) {
+        return {
+            mode: 'write_blocked',
+            errorCode: 'WRITE_BLOCKED',
+            guard: 'canonical_path',
+            recoveryHint: writeResult.recovery_hint ?? 'Use the canonical memory/YYYY-MM-DD.md path before allowing generated writes.',
+        };
+    }
+    return {
+        mode: 'write_failed',
+        errorCode: 'WRITE_FAILED',
+        guard: 'canonical_path',
+        recoveryHint: writeResult.recovery_hint,
+    };
+}
+function calendarDateFromTimestamp(timestamp) {
+    const parts = (0, time_utils_1.parseTimestampParts)(timestamp);
+    if (!parts)
+        throw new Error(`Generated timestamp is not parseable: ${timestamp}`);
+    return (0, time_utils_1.formatDate)(parts);
+}
+function buildReasonerNotes(reasoned) {
+    const notes = [reasoned.rationale.summary];
+    const interpretation = reasoned.time_interpretation?.summary?.trim();
+    if (interpretation) {
+        notes.push(`Time interpretation: ${interpretation}`);
+    }
+    return notes;
+}
+function persistTraceIfConfigured(output, input, deps, requestedRange) {
+    if (!deps.traceLogPath)
+        return false;
+    (0, trace_log_1.appendTraceLog)({
+        trace_id: output.trace_id,
+        event: 'timeline_resolve',
+        ts: new Date().toISOString(),
+        payload: {
+            ok: output.ok,
+            requested_range: requestedRange,
+            error: output.ok ? null : output.error,
+            resolution_mode: output.resolution_summary.mode,
+            notes: output.notes,
+            trace: output.trace ?? null,
+        },
+    }, deps.traceLogPath);
+    return true;
+}
+function finalizeTimelineOutput(output, input, deps, requestedRange) {
+    persistTraceIfConfigured(output, input, deps, requestedRange);
+    if (!input.trace) {
+        delete output.trace;
+    }
+    return output;
+}
+function makeRequestId() {
+    return `timeline-request-${Date.now()}-${Math.floor(Math.random() * 100000)}`;
+}
+async function maybePlanTimelineQuery(input, deps, anchor) {
+    if (!deps.planTimelineQuery) {
+        throw new Error('Timeline query planner dependency missing');
+    }
+    const plan = await deps.planTimelineQuery(input, anchor);
+    if (!plan) {
+        throw new Error('Timeline query planner returned no decision');
+    }
+    return plan;
+}
+function buildWorldHooks(timestamp) {
+    const parts = (0, time_utils_1.parseTimestampParts)(timestamp);
+    if (!parts) {
+        return { weekday: true, holiday_key: null };
+    }
+    const date = (0, time_utils_1.formatDate)(parts);
+    return {
+        weekday: ![0, 6].includes((0, time_utils_1.dayOfWeek)(parts)),
+        holiday_key: (0, holidays_1.getHoliday)(date),
+    };
+}
+function buildReadOnlyHitOutput(selectedFact, traceId, window, collector, reasoned) {
+    const date = selectedFact.calendar_date;
+    const fp = (0, fingerprint_1.computeFingerprint)(date, selectedFact.location, selectedFact.action, selectedFact.timestamp);
+    const episode = (0, parse_memory_1.mapToEpisode)({
+        timestamp: selectedFact.timestamp,
+        location: selectedFact.location,
+        action: selectedFact.action,
+        emotionTags: selectedFact.emotion_tags,
+        appearance: selectedFact.appearance,
+        internalMonologue: selectedFact.internal_monologue,
+        parseLevel: selectedFact.parse_level,
+        confidence: selectedFact.confidence,
+    }, buildWorldHooks(selectedFact.timestamp), fp);
+    return {
+        ok: true,
+        schema_version: '1.0',
+        trace_id: traceId,
+        resolution_summary: {
+            mode: 'read_only_hit',
+            writes_attempted: 0,
+            writes_succeeded: 0,
+            sources: collector.source_order,
+            confidence_min: selectedFact.confidence,
+            confidence_max: selectedFact.confidence,
+        },
+        result: {
+            schema_version: '1.0',
+            document_type: 'timeline.window',
+            anchor: { now: window.end, timezone: window.timezone },
+            window: {
+                calendar_date: window.calendar_date,
+                preset: window.query_range,
+                semantic_target: window.semantic_target,
+                collection_scope: window.collection_scope,
+                start: window.start,
+                end: window.end,
+                idempotency_key: fp,
+            },
+            resolution: {
+                mode: 'read_only_hit',
+                notes: buildReasonerNotes(reasoned).join(' | '),
+            },
+            consumption: (0, build_consumption_view_1.buildConsumptionView)({
+                preset: window.query_range,
+                semanticTarget: window.semantic_target,
+                collectionScope: window.collection_scope,
+                resolutionMode: 'read_only_hit',
+                reasoned,
+                episode,
+                sourceType: 'canon',
+            }),
+            episodes: [episode],
+        },
+        notes: buildReasonerNotes(reasoned),
+    };
+}
+function buildEmptyOutput(traceId, window, collector, reasoned) {
+    return {
+        ok: true,
+        schema_version: '1.0',
+        trace_id: traceId,
+        resolution_summary: {
+            mode: 'empty_window',
+            writes_attempted: 0,
+            writes_succeeded: 0,
+            sources: collector.source_order,
+            confidence_min: 0,
+            confidence_max: 0,
+        },
+        result: {
+            schema_version: '1.0',
+            document_type: 'timeline.window',
+            anchor: { now: window.end, timezone: window.timezone },
+            window: {
+                calendar_date: window.calendar_date,
+                preset: window.query_range,
+                semantic_target: window.semantic_target,
+                collection_scope: window.collection_scope,
+                start: window.start,
+                end: window.end,
+                idempotency_key: 'none',
+            },
+            resolution: {
+                mode: 'empty_window',
+                notes: buildReasonerNotes(reasoned).join(' | '),
+            },
+            consumption: (0, build_consumption_view_1.buildConsumptionView)({
+                preset: window.query_range,
+                semanticTarget: window.semantic_target,
+                collectionScope: window.collection_scope,
+                resolutionMode: 'empty_window',
+                reasoned,
+                sourceType: 'none',
+            }),
+            episodes: [],
+        },
+        notes: buildReasonerNotes(reasoned),
+    };
+}
+async function timelineResolve(input, dependencyOverrides) {
+    const deps = getEffectiveTimelineDependencies(dependencyOverrides);
+    let sourceOrder = [];
+    let requestedRange = 'unknown';
+    try {
+        validateTimelineResolveInput(input);
+        const currentTime = await deps.currentTime();
+        const queryPlan = await maybePlanTimelineQuery(input, deps, {
+            now: currentTime.now,
+            timezone: currentTime.timezone,
+        });
+        requestedRange = queryPlan.target_time_range;
+        const window = (0, resolve_window_1.resolveWindow)(queryPlan, currentTime.now, currentTime.timezone);
+        const sources = await (0, collect_sources_1.collectSources)(deps, window, input);
+        sourceOrder = sources.sourceOrder;
+        const collector = (0, collect_timeline_request_1.buildTimelineCollectorOutput)(makeRequestId(), input, window, sources);
+        if (!deps.reasonTimeline) {
+            throw new Error('Timeline reasoner dependency missing');
+        }
+        const reasoned = await deps.reasonTimeline(collector);
+        if (!reasoned) {
+            throw new Error('Timeline reasoner returned no decision');
+        }
+        const guard = (0, runtime_guard_1.validateTimelineReasonerOutput)(collector, reasoned);
+        if (!guard.ok) {
+            throw new Error(`Invalid reasoner output: ${guard.block_reason}`);
+        }
+        let output;
+        let traceAppearance = { inherited: false, reason: 'not-applicable' };
+        let traceWrite = {
+            attempted: false,
+            succeeded: false,
+            guard: 'not_attempted',
+            outcome: 'not_attempted',
+            writer: 'stella-timeline-plugin',
+        };
+        let traceFingerprint = {
+            checked: collector.candidate_facts.length > 0,
+            matched: false,
+            compared_episodes: collector.candidate_facts.length,
+            reason: reasoned.rationale.summary,
+        };
+        let decision = {
+            resolution_mode: guard.outcome === 'reuse_existing_fact'
+                ? 'read_only_hit'
+                : guard.outcome === 'generate_new_fact'
+                    ? 'generated_new'
+                    : 'empty_window',
+            write_outcome: traceWrite.outcome,
+            category: reasoned.request_type,
+        };
+        if (guard.outcome === 'reuse_existing_fact' && guard.selected_fact) {
+            output = buildReadOnlyHitOutput(guard.selected_fact, '', window, collector, reasoned);
+            traceAppearance = {
+                inherited: false,
+                reason: 'existing canon reused after LLM reasoner selected a matching fact',
+                source_episode_timestamp: guard.selected_fact.timestamp,
+            };
+            traceFingerprint = {
+                checked: collector.candidate_facts.length > 0,
+                matched: true,
+                compared_episodes: collector.candidate_facts.length,
+                idempotency_key: output.result?.window.idempotency_key,
+                matched_episode_timestamp: guard.selected_fact.timestamp,
+                reason: reasoned.rationale.summary,
+            };
+            decision = {
+                resolution_mode: output.resolution_summary.mode,
+                write_outcome: traceWrite.outcome,
+                category: reasoned.request_type,
+            };
+        }
+        else if (guard.outcome === 'generate_new_fact' && guard.generated_fact) {
+            const generated = (0, materialize_generated_candidate_1.materializeGeneratedCandidate)(window, sources, guard.generated_fact, guard.generated_fact.reason || reasoned.rationale.summary || 'llm-guided semantic timeline synthesis');
+            traceAppearance = generated.appearance;
+            const generatedCalendarDate = calendarDateFromTimestamp(generated.parsed.timestamp);
+            const requestedPath = deps.memoryFilePath
+                ? deps.memoryFilePath(generatedCalendarDate)
+                : `memory/${generatedCalendarDate}.md`;
+            let filePath = requestedPath;
+            let writeResult = {
+                success: false,
+                written_at: '',
+                outcome: 'failed',
+                error: 'write dependency missing',
+                recovery_hint: 'Configure the timeline writer dependencies before allowing generated writes.',
+            };
+            let writeGuard = 'canonical_path';
+            try {
+                filePath = (0, daily_log_1.assertCanonicalDailyLogPath)(requestedPath, generatedCalendarDate, deps.canonicalRootName || 'memory');
+                writeResult = deps.writeEpisode
+                    ? await (0, lock_1.withFileLock)(filePath, async () => deps.writeEpisode({
+                        timestamp: generated.parsed.timestamp,
+                        location: generated.parsed.location,
+                        action: generated.parsed.action,
+                        emotionTags: generated.parsed.emotionTags,
+                        appearance: generated.parsed.appearance,
+                        internalMonologue: generated.parsed.internalMonologue,
+                        filePath,
+                        confidence: generated.parsed.confidence,
+                    }))
+                    : writeResult;
+            }
+            catch (error) {
+                if (error instanceof lock_1.FileLockError) {
+                    writeGuard = 'lock';
+                    writeResult = {
+                        success: false,
+                        written_at: '',
+                        outcome: 'conflict',
+                        error_code: 'LOCK_EXISTS',
+                        error: error.message,
+                        recovery_hint: 'Retry once the current timeline writer releases the file lock.',
+                    };
+                }
+                else {
+                    writeResult = {
+                        success: false,
+                        written_at: '',
+                        outcome: 'failed',
+                        error_code: String(error.message || '').includes('Canonical daily logs') ? 'IO_ERROR' : undefined,
+                        error: error.message,
+                        recovery_hint: String(error.message || '').includes('Canonical daily logs')
+                            ? 'Use the canonical memory/YYYY-MM-DD.md path before allowing generated writes.'
+                            : undefined,
+                    };
+                }
+            }
+            const normalizedWriteResult = writeResult.success && !writeResult.outcome
+                ? { ...writeResult, outcome: 'appended' }
+                : writeResult;
+            const failedWrite = !normalizedWriteResult.success ? classifyWriteFailure(normalizedWriteResult) : null;
+            if (failedWrite) {
+                writeGuard = failedWrite.guard;
+            }
+            const resolutionMode = normalizedWriteResult.success
+                ? normalizedWriteResult.outcome === 'noop_existing'
+                    ? 'already_present'
+                    : 'generated_new'
+                : failedWrite?.mode ?? 'write_failed';
+            const resolutionNotes = normalizedWriteResult.success
+                ? normalizedWriteResult.outcome === 'noop_existing'
+                    ? 'a matching canon entry already existed, so the append-only writer skipped the write'
+                    : 'generated candidate persisted via append-only writer'
+                : normalizedWriteResult.error;
+            traceWrite = {
+                attempted: true,
+                succeeded: normalizedWriteResult.success && normalizedWriteResult.outcome === 'appended',
+                file_path: filePath,
+                outcome: normalizedWriteResult.outcome,
+                error_code: normalizedWriteResult.error_code,
+                error: normalizedWriteResult.success ? undefined : normalizedWriteResult.error,
+                recovery_hint: normalizedWriteResult.recovery_hint,
+                guard: writeGuard,
+                writer: 'stella-timeline-plugin',
+            };
+            traceFingerprint = {
+                checked: true,
+                matched: false,
+                compared_episodes: collector.candidate_facts.length,
+                idempotency_key: normalizedWriteResult.idempotency_key || generated.idempotencyKey,
+                reason: generated.generationReason,
+            };
+            decision = {
+                resolution_mode: resolutionMode,
+                write_outcome: normalizedWriteResult.outcome,
+                category: normalizedWriteResult.success ? reasoned.request_type : 'write_failure',
+                error_code: failedWrite?.errorCode,
+            };
+            output = {
+                ok: true,
+                schema_version: '1.0',
+                trace_id: '',
+                resolution_summary: {
+                    mode: resolutionMode,
+                    writes_attempted: 1,
+                    writes_succeeded: normalizedWriteResult.success && normalizedWriteResult.outcome === 'appended' ? 1 : 0,
+                    sources: sources.sourceOrder,
+                    confidence_min: generated.parsed.confidence,
+                    confidence_max: generated.parsed.confidence,
+                },
+                result: {
+                    schema_version: '1.0',
+                    document_type: 'timeline.window',
+                    anchor: { now: window.end, timezone: window.timezone },
+                    window: {
+                        calendar_date: generatedCalendarDate,
+                        preset: window.query_range,
+                        semantic_target: window.semantic_target,
+                        collection_scope: window.collection_scope,
+                        start: window.start,
+                        end: window.end,
+                        idempotency_key: normalizedWriteResult.idempotency_key || generated.idempotencyKey,
+                    },
+                    resolution: {
+                        mode: resolutionMode,
+                        notes: [...buildReasonerNotes(reasoned), resolutionNotes].join(' | '),
+                    },
+                    consumption: (0, build_consumption_view_1.buildConsumptionView)({
+                        preset: window.query_range,
+                        semanticTarget: window.semantic_target,
+                        collectionScope: window.collection_scope,
+                        resolutionMode,
+                        reasoned,
+                        episode: generated.episode,
+                        sourceType: normalizedWriteResult.success ? 'generated' : 'generated',
+                    }),
+                    episodes: [generated.episode],
+                },
+                notes: buildReasonerNotes(reasoned).concat(generated.notes, normalizedWriteResult.success
+                    ? normalizedWriteResult.outcome === 'noop_existing'
+                        ? [`A matching canon entry was already present at ${filePath}; append skipped.`]
+                        : [`Generated episode persisted to ${filePath}.`]
+                    : [
+                        `Generation attempted but write failed: ${normalizedWriteResult.error ?? 'unknown error'}.`,
+                        ...(normalizedWriteResult.recovery_hint ? [`Recovery hint: ${normalizedWriteResult.recovery_hint}`] : []),
+                    ]),
+            };
+        }
+        else {
+            output = buildEmptyOutput('', window, collector, reasoned);
+            traceAppearance = {
+                inherited: false,
+                reason: 'no-canon-hit',
+            };
+            traceWrite = {
+                attempted: false,
+                succeeded: false,
+                guard: 'not_attempted',
+                outcome: 'not_attempted',
+                writer: 'stella-timeline-plugin',
+            };
+            traceFingerprint = {
+                checked: false,
+                matched: false,
+                compared_episodes: collector.candidate_facts.length,
+                reason: reasoned.rationale.summary,
+            };
+            decision = {
+                resolution_mode: output.resolution_summary.mode,
+                write_outcome: traceWrite.outcome,
+                category: reasoned.request_type,
+            };
+        }
+        const trace = (0, trace_1.buildTrace)({
+            requested_range: requestedRange,
+            actual_range: window.semantic_target,
+            source_order: sources.sourceOrder,
+            source_summary: {
+                sessions_history_count: sources.sessionsHistory.length,
+                sessions_history_preview: sources.sessionsHistory[0] || null,
+                memory_chars: sources.dailyLogs.reduce((total, entry) => total + entry.raw_content.length, 0),
+                memory_search_count: sources.memorySearch.length,
+                memory_search_preview: sources.memorySearch.slice(0, 3),
+                parsed_episode_count: collector.candidate_facts.length,
+                selected_episode_timestamp: guard.selected_fact?.timestamp,
+            },
+            fingerprint: traceFingerprint,
+            appearance: traceAppearance,
+            write: traceWrite,
+            decision,
+            notes: output.notes,
+        });
+        output.trace_id = trace.trace_id;
+        output.trace = trace;
+        return finalizeTimelineOutput(output, input, deps, requestedRange);
+    }
+    catch (error) {
+        const timelineError = error instanceof Error ? error : new Error(String(error));
+        const errorCode = classifyTimelineResolveError(timelineError);
+        const trace = (0, trace_1.buildTrace)({
+            requested_range: requestedRange,
+            actual_range: 'error',
+            source_order: sourceOrder,
+            source_summary: {
+                sessions_history_count: 0,
+                sessions_history_preview: null,
+                memory_chars: 0,
+                memory_search_count: 0,
+                memory_search_preview: [],
+                parsed_episode_count: 0,
+            },
+            fingerprint: {
+                checked: false,
+                matched: false,
+                compared_episodes: 0,
+                reason: timelineError.message,
+            },
+            appearance: { inherited: false, reason: 'error' },
+            write: {
+                attempted: false,
+                succeeded: false,
+                guard: 'not_attempted',
+                outcome: 'not_attempted',
+                writer: 'stella-timeline-plugin',
+            },
+            decision: {
+                resolution_mode: 'error',
+                write_outcome: 'not_attempted',
+                category: 'error',
+                error_code: errorCode,
+            },
+            notes: [timelineError.message],
+        });
+        const output = {
+            ok: false,
+            schema_version: '1.0',
+            trace_id: trace.trace_id,
+            resolution_summary: {
+                mode: 'error',
+                writes_attempted: 0,
+                writes_succeeded: 0,
+                sources: sourceOrder,
+                confidence_min: 0,
+                confidence_max: 0,
+            },
+            notes: [timelineError.message],
+            error: {
+                code: errorCode,
+                message: timelineError.message,
+            },
+            trace,
+        };
+        return finalizeTimelineOutput(output, input, deps, requestedRange);
+    }
+}
+exports.timelineResolveToolSpec = {
+    name: 'timeline_resolve',
+    description: '处理“你在干嘛”“你现在在哪”“最近有什么有趣的事吗”“昨晚八点你在做什么”这类时间现实与回忆问题的统一入口；直接接收自然语言 query，内部会先理解时间语义，再检索或生成并 append-only 写入 canon。',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+    },
+    run: timelineResolve,
+};