stella-timeline-plugin 2.0.5 → 2.0.7

package/README.md

@@ -63,7 +63,7 @@ It is built for immersive social chat first.
 ### 1. Install the plugin
 
 ```bash
-openclaw plugins install stella-timeline-plugin --pin
+openclaw plugins install stella-timeline-plugin
 openclaw plugins enable stella-timeline-plugin
 ```
 

package/README_ZH.md

@@ -63,7 +63,7 @@ Timeline 为 OpenClaw 增加了一层专门的时间感知与回忆能力，让
 ### 1. 安装插件
 
 ```bash
-openclaw plugins install stella-timeline-plugin --pin
+openclaw plugins install stella-timeline-plugin
 openclaw plugins enable stella-timeline-plugin
 ```
 

package/dist/src/plugin_metadata.js

@@ -3,7 +3,7 @@ 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_VERSION = '2.0.7';
 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/openclaw_timeline_runtime.js

@@ -33,12 +33,23 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setOpenClawPluginRuntimeModuleLoaderForTests = setOpenClawPluginRuntimeModuleLoaderForTests;
+exports.resetOpenClawPluginRuntimeModuleLoaderForTests = resetOpenClawPluginRuntimeModuleLoaderForTests;
 exports.makeOpenClawTimelineResolveToolFactory = makeOpenClawTimelineResolveToolFactory;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const conversation_context_1 = require("./conversation_context");
 const time_utils_1 = require("../lib/time-utils");
 const timeline_resolve_1 = require("../tools/timeline_resolve");
+let openClawPluginRuntimeModuleLoader = () => {
+    try {
+        return require('openclaw/plugin-sdk/runtime');
+    }
+    catch {
+        return null;
+    }
+};
+let cachedLateBoundGatewaySubagentRuntime;
 function readString(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
@@ -67,6 +78,78 @@ function wrapToolPayload(payload) {
         details: payload,
     };
 }
+function isSubagentRuntimeAvailable(runtime) {
+    return Boolean(runtime
+        && typeof runtime.run === 'function'
+        && typeof runtime.waitForRun === 'function'
+        && typeof runtime.getSessionMessages === 'function');
+}
+function isUnavailableSubagentRuntimeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes('Plugin runtime subagent methods are only available during a gateway request.');
+}
+function getLateBoundGatewaySubagentRuntime(pluginApi) {
+    if (cachedLateBoundGatewaySubagentRuntime !== undefined) {
+        return cachedLateBoundGatewaySubagentRuntime || undefined;
+    }
+    const runtimeModule = openClawPluginRuntimeModuleLoader();
+    const lateBoundRuntime = runtimeModule?.createPluginRuntime?.({
+        allowGatewaySubagentBinding: true,
+    });
+    const lateBoundSubagent = lateBoundRuntime?.subagent;
+    const subagentRuntime = isSubagentRuntimeAvailable(lateBoundSubagent)
+        ? lateBoundSubagent
+        : undefined;
+    if (!subagentRuntime) {
+        pluginApi.logger?.debug?.('timeline late-bound gateway subagent runtime unavailable');
+    }
+    cachedLateBoundGatewaySubagentRuntime = subagentRuntime ?? null;
+    return subagentRuntime;
+}
+async function withPreferredSubagentRuntime(pluginApi, purpose, execute) {
+    const injectedSubagent = pluginApi.runtime?.subagent;
+    const injectedRuntime = isSubagentRuntimeAvailable(injectedSubagent)
+        ? injectedSubagent
+        : undefined;
+    let injectedError;
+    if (injectedRuntime) {
+        try {
+            return await execute(injectedRuntime);
+        }
+        catch (error) {
+            injectedError = error;
+            if (!isUnavailableSubagentRuntimeError(error)) {
+                throw error;
+            }
+            pluginApi.logger?.debug?.(`timeline ${purpose} retrying with late-bound gateway subagent runtime`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const lateBoundRuntime = getLateBoundGatewaySubagentRuntime(pluginApi);
+    if (lateBoundRuntime && lateBoundRuntime !== injectedRuntime) {
+        return execute(lateBoundRuntime);
+    }
+    if (injectedError) {
+        throw injectedError;
+    }
+    throw new Error(`${purpose} dependency missing`);
+}
+function setOpenClawPluginRuntimeModuleLoaderForTests(loader) {
+    openClawPluginRuntimeModuleLoader = loader;
+    cachedLateBoundGatewaySubagentRuntime = undefined;
+}
+function resetOpenClawPluginRuntimeModuleLoaderForTests() {
+    openClawPluginRuntimeModuleLoader = () => {
+        try {
+            return require('openclaw/plugin-sdk/runtime');
+        }
+        catch {
+            return null;
+        }
+    };
+    cachedLateBoundGatewaySubagentRuntime = undefined;
+}
 function resolveWorkspaceDir(pluginApi, toolContext) {
     if (toolContext.workspaceDir)
         return toolContext.workspaceDir;
@@ -616,61 +699,59 @@ function buildFallbackReasonerOutput(collector, error) {
 function createTimelineQueryPlanner(pluginApi, toolContext, runtimeConfig) {
     return async (input, anchor) => {
         try {
-            const subagentRuntime = pluginApi.runtime?.subagent;
-            if (!subagentRuntime?.run || !subagentRuntime.waitForRun || !subagentRuntime.getSessionMessages) {
-                throw new Error('Timeline query planner dependency missing');
-            }
             if (!String(input.query || '').trim()) {
                 throw new Error('Timeline query planner dependency missing query');
             }
             const requestId = makePlannerRequestId();
             const baseSessionKey = toolContext.sessionKey || `plugin:${runtimeConfig.reasonerSessionPrefix}`;
             const plannerSessionKey = `${baseSessionKey}:${runtimeConfig.reasonerSessionPrefix}:planner:${requestId}`;
-            try {
-                const runResult = await subagentRuntime.run({
-                    sessionKey: plannerSessionKey,
-                    message: buildTimelineQueryPlannerMessage(input, anchor, requestId),
-                    extraSystemPrompt: buildTimelineQueryPlannerSystemPrompt(),
-                    deliver: false,
-                    idempotencyKey: requestId,
-                });
-                const waitResult = await subagentRuntime.waitForRun({
-                    runId: runResult.runId,
-                    timeoutMs: runtimeConfig.reasonerTimeoutMs,
-                });
-                if (waitResult.status === 'timeout') {
-                    throw new Error('Timeline query planner returned no decision');
-                }
-                if (waitResult.status === 'error') {
-                    throw new Error(waitResult.error || 'Timeline query planner returned no decision');
-                }
-                const session = await subagentRuntime.getSessionMessages({
-                    sessionKey: plannerSessionKey,
-                    limit: runtimeConfig.reasonerMessageLimit,
-                });
-                const jsonText = extractJsonObjectFromMessages(session.messages || [], 'Timeline query planner', requestId);
-                const parsed = JSON.parse(jsonText);
-                if (parsed.request_id && parsed.request_id !== requestId) {
-                    throw new Error('Timeline query planner returned mismatched request_id');
-                }
-                if (!['now', 'past_point', 'past_range'].includes(parsed.target_time_range)) {
-                    throw new Error('Timeline query planner returned an invalid target_time_range');
-                }
-                return parsed;
-            }
-            finally {
+            return await withPreferredSubagentRuntime(pluginApi, 'Timeline query planner', async (subagentRuntime) => {
                 try {
-                    await subagentRuntime.deleteSession?.({
+                    const runResult = await subagentRuntime.run({
                         sessionKey: plannerSessionKey,
-                        deleteTranscript: true,
+                        message: buildTimelineQueryPlannerMessage(input, anchor, requestId),
+                        extraSystemPrompt: buildTimelineQueryPlannerSystemPrompt(),
+                        deliver: false,
+                        idempotencyKey: requestId,
                     });
-                }
-                catch (error) {
-                    pluginApi.logger?.debug?.('timeline query planner session cleanup skipped', {
-                        error: error instanceof Error ? error.message : String(error),
+                    const waitResult = await subagentRuntime.waitForRun({
+                        runId: runResult.runId,
+                        timeoutMs: runtimeConfig.reasonerTimeoutMs,
+                    });
+                    if (waitResult.status === 'timeout') {
+                        throw new Error('Timeline query planner returned no decision');
+                    }
+                    if (waitResult.status === 'error') {
+                        throw new Error(waitResult.error || 'Timeline query planner returned no decision');
+                    }
+                    const session = await subagentRuntime.getSessionMessages({
+                        sessionKey: plannerSessionKey,
+                        limit: runtimeConfig.reasonerMessageLimit,
                     });
+                    const jsonText = extractJsonObjectFromMessages(session.messages || [], 'Timeline query planner', requestId);
+                    const parsed = JSON.parse(jsonText);
+                    if (parsed.request_id && parsed.request_id !== requestId) {
+                        throw new Error('Timeline query planner returned mismatched request_id');
+                    }
+                    if (!['now', 'past_point', 'past_range'].includes(parsed.target_time_range)) {
+                        throw new Error('Timeline query planner returned an invalid target_time_range');
+                    }
+                    return parsed;
                 }
-            }
+                finally {
+                    try {
+                        await subagentRuntime.deleteSession?.({
+                            sessionKey: plannerSessionKey,
+                            deleteTranscript: true,
+                        });
+                    }
+                    catch (error) {
+                        pluginApi.logger?.debug?.('timeline query planner session cleanup skipped', {
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            });
         }
         catch (error) {
             pluginApi.logger?.warn?.('timeline query planner fallback engaged', {
@@ -751,50 +832,48 @@ function buildTimelineReasonerMessage(collector) {
 function createSubagentReasoner(pluginApi, toolContext, runtimeConfig) {
     return async (collector) => {
         try {
-            const subagentRuntime = pluginApi.runtime?.subagent;
-            if (!subagentRuntime?.run || !subagentRuntime.waitForRun || !subagentRuntime.getSessionMessages) {
-                throw new Error('Timeline reasoner dependency missing');
-            }
             const baseSessionKey = toolContext.sessionKey || `plugin:${runtimeConfig.reasonerSessionPrefix}`;
             const reasonerSessionKey = `${baseSessionKey}:${runtimeConfig.reasonerSessionPrefix}:${collector.request_id}`;
-            try {
-                const runResult = await subagentRuntime.run({
-                    sessionKey: reasonerSessionKey,
-                    message: buildTimelineReasonerMessage(collector),
-                    extraSystemPrompt: buildTimelineReasonerSystemPrompt(),
-                    deliver: false,
-                    idempotencyKey: collector.request_id,
-                });
-                const waitResult = await subagentRuntime.waitForRun({
-                    runId: runResult.runId,
-                    timeoutMs: runtimeConfig.reasonerTimeoutMs,
-                });
-                if (waitResult.status === 'timeout') {
-                    throw new Error('Timeline reasoner returned no decision');
-                }
-                if (waitResult.status === 'error') {
-                    throw new Error(waitResult.error || 'Timeline reasoner returned no decision');
-                }
-                const session = await subagentRuntime.getSessionMessages({
-                    sessionKey: reasonerSessionKey,
-                    limit: runtimeConfig.reasonerMessageLimit,
-                });
-                const jsonText = extractJsonObjectFromMessages(session.messages || [], 'Timeline reasoner', collector.request_id);
-                return JSON.parse(jsonText);
-            }
-            finally {
+            return await withPreferredSubagentRuntime(pluginApi, 'Timeline reasoner', async (subagentRuntime) => {
                 try {
-                    await subagentRuntime.deleteSession?.({
+                    const runResult = await subagentRuntime.run({
                         sessionKey: reasonerSessionKey,
-                        deleteTranscript: true,
+                        message: buildTimelineReasonerMessage(collector),
+                        extraSystemPrompt: buildTimelineReasonerSystemPrompt(),
+                        deliver: false,
+                        idempotencyKey: collector.request_id,
                     });
-                }
-                catch (error) {
-                    pluginApi.logger?.debug?.('timeline reasoner session cleanup skipped', {
-                        error: error instanceof Error ? error.message : String(error),
+                    const waitResult = await subagentRuntime.waitForRun({
+                        runId: runResult.runId,
+                        timeoutMs: runtimeConfig.reasonerTimeoutMs,
                     });
+                    if (waitResult.status === 'timeout') {
+                        throw new Error('Timeline reasoner returned no decision');
+                    }
+                    if (waitResult.status === 'error') {
+                        throw new Error(waitResult.error || 'Timeline reasoner returned no decision');
+                    }
+                    const session = await subagentRuntime.getSessionMessages({
+                        sessionKey: reasonerSessionKey,
+                        limit: runtimeConfig.reasonerMessageLimit,
+                    });
+                    const jsonText = extractJsonObjectFromMessages(session.messages || [], 'Timeline reasoner', collector.request_id);
+                    return JSON.parse(jsonText);
                 }
-            }
+                finally {
+                    try {
+                        await subagentRuntime.deleteSession?.({
+                            sessionKey: reasonerSessionKey,
+                            deleteTranscript: true,
+                        });
+                    }
+                    catch (error) {
+                        pluginApi.logger?.debug?.('timeline reasoner session cleanup skipped', {
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            });
         }
         catch (error) {
             pluginApi.logger?.warn?.('timeline reasoner fallback engaged', {
@@ -819,14 +898,13 @@ function createTimelineResolveDependencies(pluginApi, toolContext) {
         }),
         sessionsHistory: async () => {
             const sessionKey = toolContext.sessionKey;
-            const getSessionMessages = pluginApi.runtime?.subagent?.getSessionMessages;
-            if (!sessionKey || !getSessionMessages)
+            if (!sessionKey)
                 return [];
             try {
-                const session = await getSessionMessages({
+                const session = await withPreferredSubagentRuntime(pluginApi, 'timeline sessionsHistory', (subagentRuntime) => subagentRuntime.getSessionMessages({
                     sessionKey,
                     limit: runtimeConfig.sessionHistoryLimit,
-                });
+                }));
                 return normalizeSessionHistory(session.messages || [], runtimeConfig.sessionHistoryLimit);
             }
             catch (error) {
@@ -838,8 +916,7 @@ function createTimelineResolveDependencies(pluginApi, toolContext) {
         },
         conversationContext: async (window, input) => {
             const sessionKey = toolContext.sessionKey;
-            const getSessionMessages = pluginApi.runtime?.subagent?.getSessionMessages;
-            if (!sessionKey || !getSessionMessages) {
+            if (!sessionKey) {
                 return {
                     is_recently_active: false,
                     minutes_since_last_turn: null,
@@ -849,10 +926,10 @@ function createTimelineResolveDependencies(pluginApi, toolContext) {
                 };
             }
             try {
-                const session = await getSessionMessages({
+                const session = await withPreferredSubagentRuntime(pluginApi, 'timeline conversationContext', (subagentRuntime) => subagentRuntime.getSessionMessages({
                     sessionKey,
                     limit: runtimeConfig.sessionHistoryLimit,
-                });
+                }));
                 return (0, conversation_context_1.buildConversationContextFromMessages)(session.messages || [], window.end, input, runtimeConfig.conversationStickinessWindowMinutes, window.query_range);
             }
             catch (error) {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "stella-timeline-plugin",
   "name": "Stella Timeline Plugin",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "OpenClaw timeline runtime with canonical timeline_resolve, LLM-based temporal reasoning, and guarded append-only writes.",
   "entry": "dist/index.js",
   "skills": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stella-timeline-plugin",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Native OpenClaw timeline plugin with a canonical timeline_resolve tool, bundled skill routing, and guarded append-only writes.",
   "keywords": [
     "openclaw",

package/scripts/release.mjs

@@ -19,6 +19,30 @@ function syncPluginVersion() {
   }
 }
 
+function syncPluginMetadataVersion() {
+  const pkgPath = path.join(repoRoot, 'package.json');
+  const metadataPath = path.join(repoRoot, 'src', 'plugin_metadata.ts');
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const metadataSource = fs.readFileSync(metadataPath, 'utf8');
+  const nextVersion = String(pkg.version);
+
+  const versionDeclRegex = /export const TIMELINE_PLUGIN_VERSION\s*=\s*'[^']*';/;
+  // If the regex doesn't match, don't silently proceed with a wrong release.
+  if (!versionDeclRegex.test(metadataSource)) {
+    throw new Error(`Unable to sync TIMELINE_PLUGIN_VERSION in ${metadataPath}`);
+  }
+
+  const updatedSource = metadataSource.replace(
+    versionDeclRegex,
+    `export const TIMELINE_PLUGIN_VERSION = '${nextVersion}';`,
+  );
+
+  if (updatedSource !== metadataSource) {
+    fs.writeFileSync(metadataPath, `${updatedSource}\n`, 'utf8');
+  }
+}
+
 function npmCommand() {
   return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
@@ -59,6 +83,7 @@ function main() {
 
   // Keep OpenClaw plugin manifest version aligned with the npm package version.
   syncPluginVersion();
+  syncPluginMetadataVersion();
 
   run(npmCommand(), ['run', 'verify']);
   run(npmCommand(), ['publish', ...publishArgs]);