stella-timeline-plugin 2.0.1 → 2.0.3

package/dist/src/runtime/openclaw_timeline_runtime.js

@@ -317,35 +317,35 @@ function makePlannerRequestId() {
 }
 function buildTimelineQueryPlannerSystemPrompt() {
     return [
-        '你是 Timeline 插件内部的时间查询归一化器。',
-        '你的唯一任务，是把自然语言时间请求归一化为 Timeline 内部可执行的结构化时间计划。',
-        '禁止调用任何工具，禁止输出 Markdown、解释或多余文本，只输出严格 JSON。',
-        '必须遵守这些约束：',
-        '1. 你必须先判断请求属于 now、past_point、past_range 中的哪一类。',
-        '2. 不能靠关键词机械枚举，而要真正理解用户语言中的时间语义。',
-        '3. now 不输出 normalized_point / normalized_start / normalized_end。',
-        '4. past_point 必须输出 normalized_point。',
-        '5. past_range 必须输出 normalized_start 和 normalized_end。',
-        '6. 对“最近”这类口语范围，要结合 anchor.now 归一化成具体起止时间。',
-        '7. 对“昨晚”“今天”“昨天上午”这类表达，要给出符合现实习惯的合理时间范围。',
-        '8. 输出时间必须是带时区偏移的 ISO-like 时间戳。',
-        '9. 只有用户明确指向某个时刻时，才允许判为 past_point；例如“昨晚八点”“昨天上午十点”“上周六晚上九点”。',
-        '10. 只要用户问的是一个时间段或一整个时段，就必须判为 past_range；例如“昨晚在做什么”“今天都忙了什么”“最近有什么有趣的事吗”“这几天怎么样”。',
-        '11. “昨晚”本身不是时间点，而是一个晚间范围；只有“昨晚八点”这类带明确时点锚点的表达才是 past_point。',
+        'You are the internal Timeline plugin query normalizer.',
+        'Your only task is to normalize a natural-language time request into a structured time plan that Timeline can execute.',
+        'Do not call tools. Do not output Markdown, explanations, or extra text. Output strict JSON only.',
+        'You must follow these constraints:',
+        '1. First classify the request as now, past_point, or past_range.',
+        '2. Do not classify mechanically from keywords. Interpret the actual time semantics in the user request.',
+        '3. For now, do not output normalized_point / normalized_start / normalized_end.',
+        '4. For past_point, normalized_point is required.',
+        '5. For past_range, normalized_start and normalized_end are required.',
+        '6. For colloquial ranges such as “最近”, normalize into concrete bounds using anchor.now.',
+        '7. For expressions such as “昨晚”, “今天”, or “昨天上午”, produce a realistic range that fits ordinary usage.',
+        '8. All output times must be ISO-like timestamps with timezone offsets.',
+        '9. Classify as past_point only when the user clearly points to a specific moment, for example “昨晚八点”, “昨天上午十点”, or “上周六晚上九点”.',
+        '10. If the user is asking about a duration or a whole period, it must be past_range, for example “昨晚在做什么”, “今天都忙了什么”, “最近有什么有趣的事吗”, or “这几天怎么样”.',
+        '11. “昨晚” by itself is not a point in time. It is an evening range. Only expressions with an explicit anchor such as “昨晚八点” are past_point.',
     ].join('\n');
 }
 function buildTimelineQueryPlannerMessage(input, anchor, requestId) {
     return [
-        '请只根据下面的信息做时间归一化。',
-        '输出 JSON 对象，字段必须满足下列结构：',
+        'Normalize time only from the information below.',
+        'Output a JSON object with the following shape:',
         JSON.stringify({
             schema_version: '1.0',
             request_id: requestId,
             target_time_range: 'now | past_point | past_range',
-            normalized_point: 'past_point 时必填，其余省略',
-            normalized_start: 'past_range 时必填，其余省略',
-            normalized_end: 'past_range 时必填，其余省略',
-            summary: '你如何理解用户时间语义的简短说明',
+            normalized_point: 'required for past_point, omit otherwise',
+            normalized_start: 'required for past_range, omit otherwise',
+            normalized_end: 'required for past_range, omit otherwise',
+            summary: 'short summary of how you interpreted the user time semantics',
         }, null, 2),
         '',
         'input:',
@@ -357,36 +357,36 @@ function buildTimelineQueryPlannerMessage(input, anchor, requestId) {
 }
 function buildTimelineReasonerSystemPrompt() {
     return [
-        '你是 Timeline 插件内部的时间语义推理器。',
-        '你的唯一任务，是基于 collector 提供的事实包，输出一个严格符合 TimelineReasonerOutput 结构的 JSON 对象。',
-        '禁止调用任何工具，禁止引用 collector 之外的新既有事实，禁止输出 Markdown、解释或多余文本。',
-        '必须遵守这些约束：',
-        '1. 会话硬事实和已存在 canon 优先于生成。',
-        '2. 如果 collector.request.mode 是 read_only，则绝不能 generate_new_fact。',
-        '3. 如果 decision.action 是 reuse_existing_fact，selected_fact_id 必须来自 candidate_facts。',
-        '4. 如果 decision.action 是 generate_new_fact，必须给出完整 generated_fact，并且 should_write_canon=true。',
-        '5. 如果当前信息不足且不应复用或生成，才允许 return_empty。',
-        '6. continuity 字段必须如实表达是否做了延续性判断，以及判断理由。',
-        '7. request_type 只能是 now、past_point、past_range。',
-        '8. continuity 不是独立请求类型；它只是 now 或 past_point 查询中的推理结果。',
-        '9. past_point 可以通过精确命中，或通过“较早事实自然持续到目标时间点”的方式命中。',
-        '10. past_range 需要先理解已经归一化的时间范围，再从该范围内挑选最相关、最鲜活、最值得提的事实。',
-        '11. 如果用户在问“有趣”“好玩”“忙不忙”这类语义筛选词，必须先理解筛选语义，再决定复用什么事实或生成什么事实。',
-        '12. 如果为 past_point 或 past_range 生成新事实，generated_fact 应尽量提供一个合理的 timestamp，并保证它落在目标时间点或目标时间范围内，而不是默认落在当前时刻。',
-        '13. generated_fact 只输出结构化字段，不要输出自然正文、解释或额外叙述。',
-        '14. 如果 collector.persona_context.should_constrain_generation=true，则生成的新事实必须显式参考 SOUL / MEMORY / IDENTITY 中的稳定人格、语气、兴趣、生活习惯或长期约定，不能生成与这些内容冲突的生活片段。',
-        '15. 当 persona_context 中存在明确人格线索时，rationale.persona_basis 不能为空，且必须指出本次生成具体参考了哪些 persona 线索。',
-        '16. 当 persona_context 中存在明确人格线索时，rationale.constraint_basis 不能为空，且必须指出哪些长期约束限制了生成结果。',
-        '17. 不要生成通用、模板化、任何人格都能成立的空泛日常；应尽量让 location、action、emotion、appearance、internalMonologue 都体现该 persona 的生活连续性。',
-        '18. MEMORY 中的长期偏好、关系、生活节奏和与用户的长期约定，都是编织时间记忆时的重要约束；它们不是时间事实本身，但会限制什么样的生成是可信的。',
-        '19. 还必须遵守 collector.world_context 提供的现实时间逻辑：一日三餐、睡眠、工作/学习、休闲、周末、工作日、节假日的安排都应尽量符合普通现实生活节奏。',
-        '20. 如果生成的是凌晨或深夜时段，优先考虑睡眠、休息、安静活动；如果生成的是早餐/午餐/晚餐，则时间应落在合理餐段；不要生成明显违背现实作息的片段。',
-        '21. 如果 decision.action 是 generate_new_fact，generated_fact.sceneSemantics 必须完整输出，用来说明本次编织的事件属于什么活动类型、与当天已知状态是什么连续关系，以及为什么这样判断。',
-        '22. 如果 decision.action 是 generate_new_fact，generated_fact.appearanceLogic 必须完整输出，用来说明这次事件是否延续当天穿着、是否需要换装、换装原因是什么、最终服装类型属于哪一类。',
-        '23. 外貌与穿着必须依赖具体事件本身，而不是脱离事件单独生成；例如运动、洗澡、入睡、正式出门、买到并换上新衣物，都会显著影响 appearanceLogic。',
-        '24. 如果没有足够理由触发换装，优先认为当天穿着具有连续性；不要无缘无故在同一天内频繁改变外貌描述。',
-        '25. 对 now 查询，如果 collector.conversation_context.should_prefer_conversation_continuity_for_now=true，则“刚刚还在和用户继续这段对话”应被视为最高优先级的近场现实。',
-        '26. 如果当前会话仍处于粘连窗口内，优先把当前状态理解为还在和用户继续刚才的话题、思考上一轮内容或准备回应，而不是立即跳到脱离当前会话的生活片段。',
+        'You are the internal Timeline plugin time-semantics reasoner.',
+        'Your only task is to use the collector fact bundle and output a JSON object that strictly matches TimelineReasonerOutput.',
+        'Do not call tools. Do not introduce pre-existing facts beyond the collector input. Do not output Markdown, explanations, or extra text.',
+        'You must follow these constraints:',
+        '1. Session hard facts and existing canon facts take priority over generation.',
+        '2. If collector.request.mode is read_only, you must never generate_new_fact.',
+        '3. If decision.action is reuse_existing_fact, selected_fact_id must come from candidate_facts.',
+        '4. If decision.action is generate_new_fact, you must provide a complete generated_fact and set should_write_canon=true.',
+        '5. Use return_empty only when the available information is insufficient and neither reuse nor generation is justified.',
+        '6. The continuity field must truthfully report whether continuity reasoning was used and why.',
+        '7. request_type must be one of now, past_point, or past_range.',
+        '8. continuity is not a separate request type. It is a reasoning result inside now or past_point queries.',
+        '9. past_point may hit either by exact match or by a prior fact that naturally continues to the target time.',
+        '10. For past_range, first understand the normalized range, then choose the most relevant, vivid, and worth-mentioning facts from that range.',
+        '11. If the user asks with semantic filters such as “有趣”, “好玩”, or “忙不忙”, interpret that filter first before deciding which fact to reuse or generate.',
+        '12. When generating a new fact for past_point or past_range, provide a reasonable timestamp that lands inside the target point or range instead of defaulting to the current moment.',
+        '13. generated_fact must contain structured fields only, with no free-form prose, explanation, or extra narration.',
+        '14. If collector.persona_context.should_constrain_generation=true, the new fact must explicitly respect the stable persona, tone, interests, habits, and long-term commitments described in SOUL / MEMORY / IDENTITY, and must not conflict with them.',
+        '15. When persona_context contains concrete persona signals, rationale.persona_basis must be non-empty and must name the specific persona signals used.',
+        '16. When persona_context contains concrete persona signals, rationale.constraint_basis must be non-empty and must name the long-term constraints that limited generation.',
+        '17. Do not generate generic, template-like daily scenes that could fit anyone. Let location, action, emotion, appearance, and internalMonologue reflect this persona\'s lived continuity.',
+        '18. Long-term preferences, relationships, life rhythm, and standing commitments from MEMORY are important constraints when weaving time memories. They are not time facts themselves, but they constrain what generation is believable.',
+        '19. You must also respect the real-world temporal logic in collector.world_context: meals, sleep, work/study, leisure, weekends, weekdays, and holidays should broadly fit ordinary life rhythm.',
+        '20. For late-night or pre-dawn generation, prefer sleep, rest, or quiet activities. For breakfast, lunch, or dinner scenes, keep the timestamp inside a plausible meal window. Do not generate scenes that obviously violate ordinary routine.',
+        '21. If decision.action is generate_new_fact, generated_fact.sceneSemantics must be fully populated to explain the activity type, how it relates to known same-day state, and why that judgment fits.',
+        '22. If decision.action is generate_new_fact, generated_fact.appearanceLogic must be fully populated to explain whether the day\'s outfit continues, whether a change is needed, why, and what outfit class results.',
+        '23. Appearance and clothing must depend on the concrete event itself rather than being generated independently. Exercise, bathing, sleep, formal outings, and buying/changing into new clothes are all strong appearance drivers.',
+        '24. If there is not enough reason for an outfit change, prefer same-day clothing continuity. Do not change appearance descriptions repeatedly within one day without cause.',
+        '25. For now queries, if collector.conversation_context.should_prefer_conversation_continuity_for_now=true, then “still continuing the just-active conversation with the user” should be treated as the highest-priority near-field reality.',
+        '26. If the current session is still inside the stickiness window, prefer interpreting the current state as continuing the recent topic, thinking about the last turn, or preparing a response, instead of jumping immediately to an unrelated off-thread life scene.',
     ].join('\n');
 }
 function setClock(parts, hour, minute = 0, second = 0) {
@@ -682,8 +682,8 @@ function createTimelineQueryPlanner(pluginApi, toolContext, runtimeConfig) {
 }
 function buildTimelineReasonerMessage(collector) {
     return [
-        '请只根据下面的 collector JSON 做结构化时间推理。',
-        '输出一个 JSON 对象，字段必须满足 TimelineReasonerOutput：',
+        'Perform structured time reasoning using only the collector JSON below.',
+        'Output a JSON object matching TimelineReasonerOutput:',
         JSON.stringify({
             schema_version: '1.0',
             request_id: collector.request_id,
@@ -698,7 +698,7 @@ function buildTimelineReasonerMessage(collector) {
             },
             decision: {
                 action: 'reuse_existing_fact | generate_new_fact | return_empty',
-                selected_fact_id: 'reuse_existing_fact 时必填',
+                selected_fact_id: 'required when action is reuse_existing_fact',
                 should_write_canon: true,
             },
             continuity: {

package/dist/src/tools/timeline_resolve.js

@@ -684,7 +684,7 @@ async function timelineResolve(input, dependencyOverrides) {
 }
 exports.timelineResolveToolSpec = {
     name: 'timeline_resolve',
-    description: '处理“你在干嘛”“你现在在哪”“最近有什么有趣的事吗”“昨晚八点你在做什么”这类时间现实与回忆问题的统一入口；直接接收自然语言 query，内部会先理解时间语义，再检索或生成并 append-only 写入 canon。',
+    description: 'Unified entry point for time-grounded reality and recall questions such as “你在干嘛”, “你现在在哪”, “最近有什么有趣的事吗”, or “昨晚八点你在做什么”. It accepts a natural-language query, interprets the time semantics internally, then retrieves or generates and append-only writes canon facts.',
     inputSchema: {
         type: 'object',
         properties: {

package/openclaw.plugin.json

@@ -1,54 +1,54 @@
-{
-  "id": "stella-timeline-plugin",
-  "name": "Stella Timeline Plugin",
-  "version": "2.0.0",
-  "description": "OpenClaw timeline runtime with canonical timeline_resolve, LLM-based temporal reasoning, and guarded append-only writes.",
-  "entry": "dist/index.js",
-  "skills": [
-    "skills/timeline"
-  ],
-  "configSchema": {
-    "type": "object",
-    "properties": {
-      "enableTrace": {
-        "type": "boolean",
-        "default": true,
-        "description": "Whether Timeline writes trace records for each runtime execution."
-      },
-      "traceLogPath": {
-        "type": "string",
-        "description": "Optional trace log path. Relative paths are resolved from the workspace."
-      },
-      "canonicalMemoryRoot": {
-        "type": "string",
-        "description": "Root directory for canonical timeline daily logs. Relative paths are resolved from the workspace."
-      },
-      "reasonerTimeoutMs": {
-        "type": "integer",
-        "default": 90000,
-        "description": "Timeout for the internal timeline reasoner subagent, in milliseconds."
-      },
-      "reasonerSessionPrefix": {
-        "type": "string",
-        "default": "timeline-reasoner",
-        "description": "Session key prefix used for the internal timeline reasoner subagent."
-      },
-      "reasonerMessageLimit": {
-        "type": "integer",
-        "default": 24,
-        "description": "Maximum number of messages retained when reading the internal reasoner transcript."
-      },
-      "sessionHistoryLimit": {
-        "type": "integer",
-        "default": 12,
-        "description": "Maximum number of current-session messages retained by the collector."
-      },
-      "memorySearchMaxResults": {
-        "type": "integer",
-        "default": 6,
-        "description": "Maximum number of results requested when the collector calls OpenClaw memory_search."
-      }
-    },
-    "additionalProperties": false
-  }
-}
+{
+  "id": "stella-timeline-plugin",
+  "name": "Stella Timeline Plugin",
+  "version": "2.0.0",
+  "description": "OpenClaw timeline runtime with canonical timeline_resolve, LLM-based temporal reasoning, and guarded append-only writes.",
+  "entry": "dist/index.js",
+  "skills": [
+    "skills/timeline"
+  ],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "enableTrace": {
+        "type": "boolean",
+        "default": true,
+        "description": "Whether Timeline writes trace records for each runtime execution."
+      },
+      "traceLogPath": {
+        "type": "string",
+        "description": "Optional trace log path. Relative paths are resolved from the workspace."
+      },
+      "canonicalMemoryRoot": {
+        "type": "string",
+        "description": "Root directory for canonical timeline daily logs. Relative paths are resolved from the workspace."
+      },
+      "reasonerTimeoutMs": {
+        "type": "integer",
+        "default": 90000,
+        "description": "Timeout for the internal timeline reasoner subagent, in milliseconds."
+      },
+      "reasonerSessionPrefix": {
+        "type": "string",
+        "default": "timeline-reasoner",
+        "description": "Session key prefix used for the internal timeline reasoner subagent."
+      },
+      "reasonerMessageLimit": {
+        "type": "integer",
+        "default": 24,
+        "description": "Maximum number of messages retained when reading the internal reasoner transcript."
+      },
+      "sessionHistoryLimit": {
+        "type": "integer",
+        "default": 12,
+        "description": "Maximum number of current-session messages retained by the collector."
+      },
+      "memorySearchMaxResults": {
+        "type": "integer",
+        "default": 6,
+        "description": "Maximum number of results requested when the collector calls OpenClaw memory_search."
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -1,73 +1,73 @@
-{
-  "name": "stella-timeline-plugin",
-  "version": "2.0.1",
-  "description": "Native OpenClaw timeline plugin with a canonical timeline_resolve tool, bundled skill routing, and guarded append-only writes.",
-  "keywords": [
-    "openclaw",
-    "skill",
-    "timeline",
-    "memory",
-    "ai-agent",
-    "episode",
-    "persona"
-  ],
-  "author": "tao.zang",
-  "license": "MIT-0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tower1229/Her"
-  },
-  "homepage": "https://github.com/tower1229/Her#readme",
-  "bugs": {
-    "url": "https://github.com/tower1229/Her/issues"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "scripts": {
-    "prebuild": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "node node_modules/jest/bin/jest.js --runInBand",
-    "test:unit": "node node_modules/jest/bin/jest.js --runInBand",
-    "test:smoke": "node ./scripts/run-openclaw-smoke.mjs",
-    "test:live-experience": "node ./scripts/run-openclaw-live-e2e.mjs",
-    "migrate:memory": "node ./scripts/migrate-existing-memory.mjs --apply",
-    "setup:workspace": "node ./scripts/setup-openclaw-workspace.mjs",
-    "doctor:workspace": "node ./scripts/doctor-openclaw-workspace.mjs",
-    "verify": "npm run typecheck && npm run build && npm run test:unit",
-    "pack:plugin": "npm pack",
-    "release": "node ./scripts/release.mjs"
-  },
-  "bin": {
-    "openclaw-timeline-setup": "./bin/openclaw-timeline-setup.mjs",
-    "openclaw-timeline-doctor": "./bin/openclaw-timeline-doctor.mjs"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@types/jest": "^30.0.0",
-    "@types/node": "^20.x",
-    "jest": "^29.x",
-    "ts-jest": "^29.x",
-    "typescript": "^5.x"
-  },
-  "main": "dist/index.js",
-  "files": [
-    "dist",
-    "bin",
-    "scripts",
-    "templates",
-    "skills",
-    "openclaw.plugin.json",
-    "LICENSE",
-    "README.md",
-    "README_ZH.md"
-  ],
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ]
-  }
+{
+  "name": "stella-timeline-plugin",
+  "version": "2.0.3",
+  "description": "Native OpenClaw timeline plugin with a canonical timeline_resolve tool, bundled skill routing, and guarded append-only writes.",
+  "keywords": [
+    "openclaw",
+    "skill",
+    "timeline",
+    "memory",
+    "ai-agent",
+    "episode",
+    "persona"
+  ],
+  "author": "tao.zang",
+  "license": "MIT-0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tower1229/Her"
+  },
+  "homepage": "https://github.com/tower1229/Her#readme",
+  "bugs": {
+    "url": "https://github.com/tower1229/Her/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node node_modules/jest/bin/jest.js --runInBand",
+    "test:unit": "node node_modules/jest/bin/jest.js --runInBand",
+    "test:smoke": "node ./scripts/run-openclaw-smoke.mjs",
+    "test:live-experience": "node ./scripts/run-openclaw-live-e2e.mjs",
+    "migrate:memory": "node ./scripts/migrate-existing-memory.mjs --apply",
+    "setup:workspace": "node ./scripts/setup-openclaw-workspace.mjs",
+    "doctor:workspace": "node ./scripts/doctor-openclaw-workspace.mjs",
+    "verify": "npm run typecheck && npm run build && npm run test:unit",
+    "pack:plugin": "npm pack",
+    "release": "node ./scripts/release.mjs"
+  },
+  "bin": {
+    "openclaw-timeline-setup": "./bin/openclaw-timeline-setup.mjs",
+    "openclaw-timeline-doctor": "./bin/openclaw-timeline-doctor.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.x",
+    "jest": "^29.x",
+    "ts-jest": "^29.x",
+    "typescript": "^5.x"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "bin",
+    "scripts",
+    "templates",
+    "skills",
+    "openclaw.plugin.json",
+    "LICENSE",
+    "README.md",
+    "README_ZH.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
 }

package/scripts/doctor-openclaw-workspace.mjs

@@ -1,94 +1,94 @@
-#!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import {
-  detectAgentsContract,
-  detectSoulContract,
-  normalizeRootName,
-  resolveCanonicalRootPath,
-} from './workspace-contract.mjs';
-
-function parseArgs(argv) {
-  const options = {
-    workspace: path.resolve(process.cwd()),
-    canonicalRootName: 'memory',
-  };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--workspace') {
-      options.workspace = path.resolve(argv[++i] || '');
-      continue;
-    }
-    if (arg === '--canonical-root-name') {
-      options.canonicalRootName = normalizeRootName(argv[++i] || '');
-      continue;
-    }
-    if (arg === '--help' || arg === '-h') {
-      printHelp();
-      process.exit(0);
-    }
-    throw new Error(`Unknown argument: ${arg}`);
-  }
-
-  return options;
-}
-
-function printHelp() {
-  console.log([
-    'Usage: openclaw-timeline-doctor [--workspace <dir>] [--canonical-root-name <name>]',
-    '',
-    'Checks whether the required Timeline workspace contracts are present.',
-  ].join('\n'));
-}
-
-function readText(filePath) {
-  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
-}
-
-function check(label, passed, successDetail, failureDetail) {
-  const prefix = passed ? '[ok]' : '[missing]';
-  console.log(`${prefix} ${label}: ${passed ? successDetail : failureDetail}`);
-  return passed;
-}
-
-function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const agentsPath = path.join(options.workspace, 'AGENTS.md');
-  const soulPath = path.join(options.workspace, 'SOUL.md');
-  const canonicalRootPath = resolveCanonicalRootPath(options.workspace, options.canonicalRootName);
-
-  const agentsContent = readText(agentsPath);
-  const soulContent = readText(soulPath);
-
-  let ok = true;
-  ok = check(
-    'AGENTS contract',
-    fs.existsSync(agentsPath) && detectAgentsContract(agentsContent),
-    agentsPath,
-    `${agentsPath} is missing the Timeline daily-log contract`,
-  ) && ok;
-  ok = check(
-    'SOUL contract',
-    fs.existsSync(soulPath) && detectSoulContract(soulContent),
-    soulPath,
-    `${soulPath} is missing the Timeline recall contract`,
-  ) && ok;
-  ok = check(
-    'Canonical memory root',
-    fs.existsSync(canonicalRootPath),
-    canonicalRootPath,
-    `${canonicalRootPath} does not exist`,
-  ) && ok;
-
-  if (!ok) {
-    process.exitCode = 1;
-  }
-}
-
-try {
-  main();
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  detectAgentsContract,
+  detectSoulContract,
+  normalizeRootName,
+  resolveCanonicalRootPath,
+} from './workspace-contract.mjs';
+
+function parseArgs(argv) {
+  const options = {
+    workspace: path.resolve(process.cwd()),
+    canonicalRootName: 'memory',
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--workspace') {
+      options.workspace = path.resolve(argv[++i] || '');
+      continue;
+    }
+    if (arg === '--canonical-root-name') {
+      options.canonicalRootName = normalizeRootName(argv[++i] || '');
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log([
+    'Usage: openclaw-timeline-doctor [--workspace <dir>] [--canonical-root-name <name>]',
+    '',
+    'Checks whether the required Timeline workspace contracts are present.',
+  ].join('\n'));
+}
+
+function readText(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+}
+
+function check(label, passed, successDetail, failureDetail) {
+  const prefix = passed ? '[ok]' : '[missing]';
+  console.log(`${prefix} ${label}: ${passed ? successDetail : failureDetail}`);
+  return passed;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const agentsPath = path.join(options.workspace, 'AGENTS.md');
+  const soulPath = path.join(options.workspace, 'SOUL.md');
+  const canonicalRootPath = resolveCanonicalRootPath(options.workspace, options.canonicalRootName);
+
+  const agentsContent = readText(agentsPath);
+  const soulContent = readText(soulPath);
+
+  let ok = true;
+  ok = check(
+    'AGENTS contract',
+    fs.existsSync(agentsPath) && detectAgentsContract(agentsContent),
+    agentsPath,
+    `${agentsPath} is missing the Timeline daily-log contract`,
+  ) && ok;
+  ok = check(
+    'SOUL contract',
+    fs.existsSync(soulPath) && detectSoulContract(soulContent),
+    soulPath,
+    `${soulPath} is missing the Timeline recall contract`,
+  ) && ok;
+  ok = check(
+    'Canonical memory root',
+    fs.existsSync(canonicalRootPath),
+    canonicalRootPath,
+    `${canonicalRootPath} does not exist`,
+  ) && ok;
+
+  if (!ok) {
+    process.exitCode = 1;
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}