stella-timeline-plugin 2.0.0

package/dist/src/lib/parse-memory.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMemoryFile = parseMemoryFile;
+exports.mapTimeOfDay = mapTimeOfDay;
+exports.mapToEpisode = mapToEpisode;
+const time_utils_1 = require("./time-utils");
+function parseMemoryFile(content) {
+    const episodes = [];
+    if (!content || !content.trim()) {
+        return episodes;
+    }
+    // Split into paragraphs by '### [' to handle sections
+    const parts = content.split(/^### \[/m);
+    for (const part of parts) {
+        if (!part.trim())
+            continue;
+        // We already split by '### [', so let's put it back to parse cleanly if needed,
+        // actually we just extract fields directly.
+        // Extract timestamp
+        const timestampMatch = part.match(/[-*]\s*Timestamp:\s*([^\n]+)/i);
+        if (!timestampMatch) {
+            continue; // Skip if no timestamp
+        }
+        const timestamp = timestampMatch[1].trim();
+        // Extract other fields with permissive matching
+        const locationMatch = part.match(/[-*]\s*Location:\s*([^\n]+)/i);
+        const actionMatch = part.match(/[-*]\s*Action:\s*([^\n]+)/i);
+        const emotionTagsMatch = part.match(/[-*]\s*Emotion_Tags:\s*\[([^\]]+)\]/i)
+            || part.match(/[-*]\s*Emotion_Tags:\s*([^\n]+)/i);
+        const appearanceMatch = part.match(/[-*]\s*Appearance:\s*([^\n]+)/i);
+        const monologueMatch = part.match(/[-*]\s*Internal_Monologue:\s*([^\n]+)/i);
+        // Extract natural text: everything after the last key-value field
+        const lastKeyValIndex = part.lastIndexOf('-');
+        let naturalText = undefined;
+        if (lastKeyValIndex !== -1) {
+            const remainingBytes = part.substring(lastKeyValIndex);
+            const afterFieldMatch = remainingBytes.match(/\n\s*([^- \n][\s\S]*)/);
+            if (afterFieldMatch && afterFieldMatch[1].trim()) {
+                naturalText = afterFieldMatch[1].trim();
+            }
+        }
+        const location = locationMatch ? locationMatch[1].trim() : "unknown";
+        const action = actionMatch ? actionMatch[1].trim() : "unknown";
+        let emotionTags = ['neutral'];
+        if (emotionTagsMatch) {
+            emotionTags = emotionTagsMatch[1].split(',').map(tag => tag.replace(/[\[\]]/g, '').trim()).filter(Boolean);
+            if (emotionTags.length === 0)
+                emotionTags = ['neutral'];
+        }
+        const appearance = appearanceMatch ? appearanceMatch[1].trim() : "unknown";
+        const internalMonologue = monologueMatch ? monologueMatch[1].trim() : undefined;
+        // Check Level A vs Level B
+        let parseLevel = 'A';
+        let confidence = 1.0;
+        if (!appearanceMatch || appearance === 'unknown') {
+            parseLevel = 'B';
+            confidence = 0.6;
+        }
+        if (!emotionTagsMatch || emotionTags[0] === 'neutral') {
+            parseLevel = 'B';
+            confidence = Math.min(confidence, 0.5);
+        }
+        episodes.push({
+            timestamp,
+            location,
+            action,
+            emotionTags,
+            appearance,
+            internalMonologue,
+            naturalText,
+            parseLevel,
+            confidence
+        });
+    }
+    return episodes;
+}
+function mapTimeOfDay(timestamp) {
+    const parts = (0, time_utils_1.parseTimestampParts)(timestamp);
+    if (parts) {
+        const hour = parts.hour;
+        if (hour >= 0 && hour <= 5)
+            return 'night';
+        if (hour >= 6 && hour <= 11)
+            return 'morning';
+        if (hour >= 12 && hour <= 17)
+            return 'afternoon';
+        return 'evening';
+    }
+    const dateObj = new Date(timestamp);
+    if (isNaN(dateObj.getTime()))
+        return 'unknown';
+    const hour = dateObj.getHours();
+    if (hour >= 0 && hour <= 5)
+        return 'night';
+    if (hour >= 6 && hour <= 11)
+        return 'morning';
+    if (hour >= 12 && hour <= 17)
+        return 'afternoon';
+    return 'evening';
+}
+function buildNarrativeSummary(parsed) {
+    const action = parsed.action && parsed.action !== 'unknown' ? parsed.action : '记录一个时间片段';
+    const location = parsed.location && parsed.location !== 'unknown' ? `在${parsed.location}` : '';
+    return `${location}${action}`;
+}
+function mapToEpisode(parsed, worldHooks, idempotencyKey, writer = 'stella-timeline-plugin') {
+    const timeOfDay = mapTimeOfDay(parsed.timestamp);
+    // End time defaults to start + 1 hour as per spec (v1 default)
+    let endStr = parsed.timestamp;
+    const parts = (0, time_utils_1.parseTimestampParts)(parsed.timestamp);
+    if (parts) {
+        endStr = (0, time_utils_1.formatTimestamp)((0, time_utils_1.addHours)(parts, 1));
+    }
+    else {
+        const startDate = new Date(parsed.timestamp);
+        if (!isNaN(startDate.getTime())) {
+            startDate.setHours(startDate.getHours() + 1);
+            const offsetMatcher = parsed.timestamp.match(/(Z|[+-]\d{2}:\d{2})$/);
+            const tzString = offsetMatcher ? offsetMatcher[1] : '';
+            const yyyy = startDate.getFullYear();
+            const mm = String(startDate.getMonth() + 1).padStart(2, '0');
+            const dd = String(startDate.getDate()).padStart(2, '0');
+            const hh = String(startDate.getHours()).padStart(2, '0');
+            const mins = String(startDate.getMinutes()).padStart(2, '0');
+            const secs = String(startDate.getSeconds()).padStart(2, '0');
+            endStr = `${yyyy}-${mm}-${dd}T${hh}:${mins}:${secs}${tzString}`;
+        }
+    }
+    return {
+        // Generate a simple v4-like uuid or mock one since it's v1.
+        // In a real env, crypto.randomUUID() could be used.
+        episode_id: `sys-${Date.now()}-${Math.floor(Math.random() * 10000)}`,
+        schema_version: "1.0",
+        document_type: "timeline.episode",
+        temporal: {
+            start: parsed.timestamp,
+            end: endStr,
+            time_of_day: timeOfDay,
+            granularity: "block"
+        },
+        narrative: {
+            summary: buildNarrativeSummary(parsed),
+            detail: parsed.internalMonologue
+        },
+        state_snapshot: {
+            scene: {
+                location_kind: 'literal',
+                location_label: parsed.location,
+                activity: parsed.action,
+                time_of_day: timeOfDay
+            },
+            emotion: {
+                primary: parsed.emotionTags[0] || "neutral",
+                secondary: parsed.emotionTags.length > 1 ? parsed.emotionTags[1] : null,
+                intensity: 0.0 // Placeholder for v1
+            },
+            appearance: {
+                outfit_style: parsed.appearance,
+                grooming: null,
+                posture_energy: null
+            }
+        },
+        world_hooks: worldHooks,
+        provenance: {
+            writer,
+            written_at: new Date().toISOString(),
+            idempotency_key: idempotencyKey,
+            confidence: parsed.confidence
+        }
+    };
+}

package/dist/src/lib/time-utils.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTimestampParts = parseTimestampParts;
+exports.formatDate = formatDate;
+exports.formatTime = formatTime;
+exports.formatTimestamp = formatTimestamp;
+exports.addHours = addHours;
+exports.dayOfWeek = dayOfWeek;
+const TIMESTAMP_RE = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(Z|[+-]\d{2}:\d{2})?$/;
+function parseTimestampParts(timestamp) {
+    const match = timestamp.trim().match(TIMESTAMP_RE);
+    if (!match)
+        return null;
+    return {
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        hour: Number(match[4]),
+        minute: Number(match[5]),
+        second: Number(match[6]),
+        offset: match[7],
+    };
+}
+function formatDate(parts) {
+    return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}`;
+}
+function formatTime(parts) {
+    return `${String(parts.hour).padStart(2, '0')}:${String(parts.minute).padStart(2, '0')}:${String(parts.second).padStart(2, '0')}`;
+}
+function formatTimestamp(parts, includeOffset = true) {
+    const base = `${formatDate(parts)}T${formatTime(parts)}`;
+    return includeOffset && parts.offset ? `${base}${parts.offset}` : base;
+}
+function addHours(parts, hoursToAdd) {
+    const date = new Date(Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second));
+    date.setUTCHours(date.getUTCHours() + hoursToAdd);
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+        hour: date.getUTCHours(),
+        minute: date.getUTCMinutes(),
+        second: date.getUTCSeconds(),
+        offset: parts.offset,
+    };
+}
+function dayOfWeek(parts) {
+    return new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay();
+}

package/dist/src/lib/timeline_semantics.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTFIT_MODES = exports.APPEARANCE_TRANSITIONS = exports.CONTINUITY_RELATIONS = exports.ACTIVITY_MODES = void 0;
+exports.isActivityMode = isActivityMode;
+exports.isContinuityRelation = isContinuityRelation;
+exports.isAppearanceTransition = isAppearanceTransition;
+exports.isOutfitMode = isOutfitMode;
+exports.ACTIVITY_MODES = [
+    'sleep',
+    'bath',
+    'meal',
+    'work_or_study',
+    'commute',
+    'exercise',
+    'social',
+    'shopping',
+    'leisure',
+    'domestic',
+    'errands',
+    'transition',
+    'rest',
+    'unknown',
+];
+exports.CONTINUITY_RELATIONS = [
+    'same_day_continuation',
+    'same_scene_continuation',
+    'shifted_scene',
+    'return_home',
+    'fresh_moment',
+    'unknown',
+];
+exports.APPEARANCE_TRANSITIONS = [
+    'inherit',
+    'change_required',
+    'change_allowed',
+    'unknown',
+];
+exports.OUTFIT_MODES = [
+    'casual_home',
+    'casual_outing',
+    'workwear',
+    'sportswear',
+    'sleepwear',
+    'bathrobe',
+    'dressed_up',
+    'fresh_purchase',
+    'unknown',
+];
+function includesValue(values, value) {
+    return values.includes(value);
+}
+function isActivityMode(value) {
+    return typeof value === 'string' && includesValue(exports.ACTIVITY_MODES, value);
+}
+function isContinuityRelation(value) {
+    return typeof value === 'string' && includesValue(exports.CONTINUITY_RELATIONS, value);
+}
+function isAppearanceTransition(value) {
+    return typeof value === 'string' && includesValue(exports.APPEARANCE_TRANSITIONS, value);
+}
+function isOutfitMode(value) {
+    return typeof value === 'string' && includesValue(exports.OUTFIT_MODES, value);
+}

package/dist/src/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/openclaw-sdk-compat.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePluginEntry = definePluginEntry;
+exports.materializePlugin = materializePlugin;
+exports.makeTimelineToolRegistration = makeTimelineToolRegistration;
+const timeline_resolve_1 = require("./tools/timeline_resolve");
+function definePluginEntry(definition) {
+    return definition;
+}
+function materializePlugin(definition) {
+    const tools = [];
+    definition.register({
+        registerTool(tool, options) {
+            tools.push({ ...tool, optional: options?.optional });
+        },
+    });
+    return {
+        id: definition.id,
+        name: definition.name,
+        description: definition.description,
+        tools,
+    };
+}
+function wrapToolData(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        data,
+    };
+}
+function makeTimelineToolRegistration() {
+    return {
+        name: timeline_resolve_1.timelineResolveToolSpec.name,
+        description: timeline_resolve_1.timelineResolveToolSpec.description,
+        parameters: timeline_resolve_1.timelineResolveToolSpec.inputSchema,
+        async execute(_callId, params) {
+            return wrapToolData(await timeline_resolve_1.timelineResolveToolSpec.run(params));
+        },
+    };
+}

package/dist/src/plugin_metadata.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMELINE_SKILL_PATHS = exports.TIMELINE_TOOL_NAMES = exports.TIMELINE_PLUGIN_DESCRIPTION = exports.TIMELINE_PLUGIN_VERSION = exports.TIMELINE_PLUGIN_NAME = exports.TIMELINE_PLUGIN_ID = void 0;
+exports.TIMELINE_PLUGIN_ID = 'stella-timeline-plugin';
+exports.TIMELINE_PLUGIN_NAME = 'Stella Timeline Plugin';
+exports.TIMELINE_PLUGIN_VERSION = '2.0.0';
+exports.TIMELINE_PLUGIN_DESCRIPTION = 'OpenClaw timeline runtime with canonical timeline_resolve, LLM-based temporal reasoning, and guarded append-only writes.';
+exports.TIMELINE_TOOL_NAMES = ['timeline_resolve'];
+exports.TIMELINE_SKILL_PATHS = ['skills/timeline'];

package/dist/src/runtime/conversation_context.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConversationContextFromMessages = buildConversationContextFromMessages;
+const time_utils_1 = require("../lib/time-utils");
+function extractMessageText(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (!value || typeof value !== 'object')
+        return '';
+    const record = value;
+    const directKeys = ['bodyText', 'body', 'text', 'contentText'];
+    for (const key of directKeys) {
+        if (typeof record[key] === 'string' && String(record[key]).trim()) {
+            return String(record[key]).trim();
+        }
+    }
+    if (Array.isArray(record.content)) {
+        const joined = record.content
+            .map((part) => extractMessageText(part))
+            .filter(Boolean)
+            .join('\n');
+        if (joined)
+            return joined;
+    }
+    if (record.content && typeof record.content === 'object') {
+        const nestedContent = extractMessageText(record.content);
+        if (nestedContent)
+            return nestedContent;
+    }
+    if (record.message && typeof record.message === 'object') {
+        const nestedMessage = extractMessageText(record.message);
+        if (nestedMessage)
+            return nestedMessage;
+    }
+    if (typeof record.type === 'string' && record.type === 'text' && typeof record.text === 'string') {
+        return record.text.trim();
+    }
+    return '';
+}
+function extractRole(value) {
+    if (!value || typeof value !== 'object')
+        return 'unknown';
+    const directRole = value.role;
+    if (typeof directRole === 'string' && directRole.trim()) {
+        return directRole.trim();
+    }
+    const nestedMessage = value.message;
+    if (nestedMessage && typeof nestedMessage === 'object') {
+        const nestedRole = nestedMessage.role;
+        if (typeof nestedRole === 'string' && nestedRole.trim()) {
+            return nestedRole.trim();
+        }
+    }
+    return 'unknown';
+}
+function extractTimestamp(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const tryKeys = (record) => {
+        const keys = ['createdAt', 'created_at', 'timestamp', 'ts', 'sentAt', 'sent_at'];
+        for (const key of keys) {
+            if (typeof record[key] === 'string' && String(record[key]).trim()) {
+                const candidate = String(record[key]).trim();
+                if (!Number.isNaN(Date.parse(candidate)) || (0, time_utils_1.parseTimestampParts)(candidate)) {
+                    return candidate;
+                }
+            }
+        }
+        return null;
+    };
+    const record = value;
+    const direct = tryKeys(record);
+    if (direct)
+        return direct;
+    const nestedMessage = record.message;
+    if (nestedMessage && typeof nestedMessage === 'object') {
+        return tryKeys(nestedMessage);
+    }
+    return null;
+}
+function minutesBetween(nowIso, thenIso) {
+    const nowMs = Date.parse(nowIso);
+    const thenMs = Date.parse(thenIso);
+    if (Number.isNaN(nowMs) || Number.isNaN(thenMs))
+        return null;
+    return Math.max(0, Math.round((nowMs - thenMs) / 60000));
+}
+function normalizeLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function summarizeTopic(messages, input) {
+    const currentQuery = normalizeLine(String(input.query || ''));
+    const candidates = [...messages]
+        .reverse()
+        .map((message) => ({
+        role: extractRole(message),
+        text: normalizeLine(extractMessageText(message)),
+    }))
+        .filter((entry) => entry.text)
+        .filter((entry) => entry.text !== currentQuery);
+    const userMessage = candidates.find((entry) => entry.role === 'user')?.text;
+    const assistantMessage = candidates.find((entry) => entry.role === 'assistant')?.text;
+    if (userMessage && assistantMessage) {
+        return `${userMessage} / ${assistantMessage}`.slice(0, 240);
+    }
+    if (userMessage)
+        return userMessage.slice(0, 180);
+    if (assistantMessage)
+        return assistantMessage.slice(0, 180);
+    return currentQuery.slice(0, 180);
+}
+function buildConversationContextFromMessages(messages, windowEnd, input, stickinessWindowMinutes, requestedRange) {
+    const lastTimestamp = [...messages]
+        .reverse()
+        .map((message) => extractTimestamp(message))
+        .find(Boolean) || undefined;
+    const minutesSinceLastTurn = lastTimestamp ? minutesBetween(windowEnd, lastTimestamp) : null;
+    const isRecentlyActive = minutesSinceLastTurn !== null && minutesSinceLastTurn <= stickinessWindowMinutes;
+    const activeTopicSummary = summarizeTopic(messages, input);
+    return {
+        is_recently_active: isRecentlyActive,
+        minutes_since_last_turn: minutesSinceLastTurn,
+        stickiness_window_minutes: stickinessWindowMinutes,
+        active_topic_summary: activeTopicSummary,
+        should_prefer_conversation_continuity_for_now: requestedRange === 'now' && isRecentlyActive,
+        last_active_timestamp: lastTimestamp,
+    };
+}