stella-timeline-plugin 2.0.0

package/openclaw.plugin.json

@@ -0,0 +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": 45000,
+        "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

@@ -0,0 +1,73 @@
+{
+  "name": "stella-timeline-plugin",
+  "version": "2.0.0",
+  "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

@@ -0,0 +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);
+}

package/scripts/migrate-existing-memory.mjs

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const args = { root: 'memory', apply: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--apply') {
+      args.apply = true;
+      continue;
+    }
+    if (token === '--root') {
+      args.root = argv[i + 1] || args.root;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function parseMemoryFile(content) {
+  const episodes = [];
+  if (!content || !content.trim()) return episodes;
+
+  const parts = content.split(/^### \[/m);
+  for (const part of parts) {
+    if (!part.trim()) continue;
+    const timestampMatch = part.match(/[-*]\s*Timestamp:\s*([^\n]+)/i);
+    if (!timestampMatch) continue;
+
+    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);
+
+    const emotionTags = emotionTagsMatch
+      ? emotionTagsMatch[1].split(',').map((tag) => tag.replace(/[\[\]]/g, '').trim()).filter(Boolean)
+      : ['neutral'];
+
+    episodes.push({
+      timestamp: timestampMatch[1].trim(),
+      location: locationMatch ? locationMatch[1].trim() : 'unknown',
+      action: actionMatch ? actionMatch[1].trim() : 'unknown',
+      emotionTags: emotionTags.length ? emotionTags : ['neutral'],
+      appearance: appearanceMatch ? appearanceMatch[1].trim() : 'unknown',
+      internalMonologue: monologueMatch ? monologueMatch[1].trim() : '',
+    });
+  }
+
+  return episodes;
+}
+
+function isSafelyStructured(content) {
+  const parts = content.split(/^### \[/m).filter((part) => part.trim());
+  if (parts.length === 0) return false;
+  return parts.every((part) => /[-*]\s*Timestamp:\s*([^\n]+)/i.test(part));
+}
+
+function formatHeading(action, timestamp) {
+  const timeMatch = timestamp.match(/(\d{2}:\d{2}:\d{2})/);
+  const time = timeMatch ? timeMatch[1] : '00:00:00';
+  return `### [${time}] ${action.slice(0, 15)}...`;
+}
+
+function formatEpisode(episode) {
+  const lines = [
+    formatHeading(episode.action, episode.timestamp),
+    '',
+    `- Timestamp: ${episode.timestamp.replace('T', ' ').replace(/([+-]\d{2}:\d{2}|Z)$/, '')}`,
+    `- Location: ${episode.location}`,
+    `- Action: ${episode.action}`,
+    `- Emotion_Tags: [${episode.emotionTags.join(', ')}]`,
+    `- Appearance: ${episode.appearance}`,
+  ];
+  if (episode.internalMonologue) {
+    lines.push(`- Internal_Monologue: ${episode.internalMonologue}`);
+  }
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function collectDailyFiles(rootDir) {
+  if (!fs.existsSync(rootDir)) return [];
+  return fs.readdirSync(rootDir)
+    .filter((name) => /^\d{4}-\d{2}-\d{2}\.md$/.test(name))
+    .map((name) => path.join(rootDir, name))
+    .sort();
+}
+
+function ensureBackup(filePath, content) {
+  const backupPath = `${filePath}.bak`;
+  if (!fs.existsSync(backupPath)) {
+    fs.writeFileSync(backupPath, content, 'utf8');
+  }
+}
+
+function migrateFile(filePath, apply) {
+  const original = fs.readFileSync(filePath, 'utf8');
+  if (!original.trim()) {
+    return { file: filePath, status: 'skipped_empty' };
+  }
+  if (!isSafelyStructured(original)) {
+    return { file: filePath, status: 'skipped_unstructured' };
+  }
+
+  const episodes = parseMemoryFile(original);
+  if (episodes.length === 0) {
+    return { file: filePath, status: 'skipped_unstructured' };
+  }
+
+  const normalized = episodes.map((episode) => formatEpisode(episode)).join('');
+  if (normalized === original) {
+    return { file: filePath, status: 'unchanged', episodes: episodes.length };
+  }
+
+  if (apply) {
+    ensureBackup(filePath, original);
+    fs.writeFileSync(filePath, normalized, 'utf8');
+  }
+
+  return {
+    file: filePath,
+    status: apply ? 'migrated' : 'would_migrate',
+    episodes: episodes.length,
+    backup: apply ? `${filePath}.bak` : undefined,
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const rootDir = path.resolve(process.cwd(), args.root);
+  const files = collectDailyFiles(rootDir);
+  const results = files.map((filePath) => migrateFile(filePath, args.apply));
+  const summary = {
+    root: rootDir,
+    apply: args.apply,
+    scanned: files.length,
+    migrated: results.filter((item) => item.status === 'migrated').length,
+    would_migrate: results.filter((item) => item.status === 'would_migrate').length,
+    unchanged: results.filter((item) => item.status === 'unchanged').length,
+    skipped_unstructured: results.filter((item) => item.status === 'skipped_unstructured').length,
+    skipped_empty: results.filter((item) => item.status === 'skipped_empty').length,
+    results,
+  };
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+main();

package/scripts/release.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const runtimeTempDir = process.platform === 'win32' ? os.tmpdir() : '/tmp';
+const npmrcPath = path.join(repoRoot, '.npmrc');
+
+function readDotEnv() {
+  const envPath = path.join(repoRoot, '.env');
+  if (!fs.existsSync(envPath)) return {};
+
+  const env = {};
+  for (const rawLine of fs.readFileSync(envPath, 'utf8').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    const separatorIndex = line.indexOf('=');
+    if (separatorIndex === -1) continue;
+
+    const key = line.slice(0, separatorIndex).trim();
+    let value = line.slice(separatorIndex + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) {
+      env[key] = value;
+    }
+  }
+
+  return env;
+}
+
+const dotEnv = readDotEnv();
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function run(command, args) {
+  const useShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    shell: useShell,
+    env: {
+      ...process.env,
+      ...dotEnv,
+      NODE_AUTH_TOKEN: process.env.NODE_AUTH_TOKEN || dotEnv.NODE_AUTH_TOKEN || dotEnv.NPM_TOKEN,
+      NPM_TOKEN: process.env.NPM_TOKEN || dotEnv.NPM_TOKEN || dotEnv.NODE_AUTH_TOKEN,
+      NPM_CONFIG_USERCONFIG: npmrcPath,
+      npm_config_cache: path.join(runtimeTempDir, 'stella-timeline-plugin-npm-cache'),
+      TMPDIR: runtimeTempDir,
+      TMP: runtimeTempDir,
+      TEMP: runtimeTempDir,
+    },
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(' ')}`);
+  }
+}
+
+function printHelp() {
+  console.log([
+    'Usage: npm run release -- [npm publish args]',
+    '',
+    'Runs verify, then publishes the current package to npm.',
+    'Reads NPM_TOKEN/NODE_AUTH_TOKEN from the project .env when present.',
+    'Examples:',
+    '  npm run release',
+    '  npm run release -- --tag next',
+    '  npm run release -- --dry-run',
+  ].join('\n'));
+}
+
+function main() {
+  const publishArgs = process.argv.slice(2);
+  if (publishArgs.includes('--help') || publishArgs.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  run(npmCommand(), ['run', 'verify']);
+  run(npmCommand(), ['publish', ...publishArgs]);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/scripts/run-openclaw-live-e2e.mjs

@@ -0,0 +1,64 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const runtimeTempDir = process.platform === 'win32' ? os.tmpdir() : '/tmp';
+
+function withRuntimeTemp(env = process.env) {
+  return {
+    ...env,
+    TMPDIR: runtimeTempDir,
+    TMP: runtimeTempDir,
+    TEMP: runtimeTempDir,
+  };
+}
+
+function resolveOnPath(binaryName) {
+  const command = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(command, [binaryName], {
+    encoding: 'utf8',
+    env: withRuntimeTemp(),
+  });
+  if (result.status !== 0) return '';
+  const firstLine = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return firstLine || '';
+}
+
+function resolveOpenClawBin() {
+  if (process.env.OPENCLAW_BIN?.trim()) return process.env.OPENCLAW_BIN.trim();
+
+  const resolved = resolveOnPath('openclaw');
+  if (resolved) return resolved;
+
+  const homeCandidate = path.join(os.homedir(), '.nvm', 'versions', 'node', 'v24.9.0', 'bin', 'openclaw');
+  if (fs.existsSync(homeCandidate)) return homeCandidate;
+
+  throw new Error(
+    [
+      '无法定位 openclaw 可执行文件。',
+      '请先确认 openclaw 已安装，或在执行前显式设置 OPENCLAW_BIN。',
+      '例如：OPENCLAW_BIN=/Users/zangtao/.nvm/versions/node/v24.9.0/bin/openclaw npm run test:live-experience',
+    ].join('\n'),
+  );
+}
+
+const openClawBin = resolveOpenClawBin();
+
+const result = spawnSync(
+  process.execPath,
+  ['node_modules/jest/bin/jest.js', '--runInBand', '--runTestsByPath', 'src/integration/openclaw-live-experience.e2e.test.ts'],
+  {
+    stdio: 'inherit',
+    env: {
+      ...withRuntimeTemp(),
+      OPENCLAW_LIVE_E2E: '1',
+      OPENCLAW_BIN: openClawBin,
+    },
+  },
+);
+
+process.exit(result.status ?? 1);

package/scripts/run-openclaw-smoke.mjs

@@ -0,0 +1,21 @@
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+
+const runtimeTempDir = process.platform === 'win32' ? os.tmpdir() : '/tmp';
+
+const result = spawnSync(
+  process.execPath,
+  ['node_modules/jest/bin/jest.js', '--runInBand', '--runTestsByPath', 'src/integration/openclaw-runtime.smoke.test.ts'],
+  {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      TMPDIR: runtimeTempDir,
+      TMP: runtimeTempDir,
+      TEMP: runtimeTempDir,
+      OPENCLAW_RUNTIME_SMOKE: '1',
+    },
+  },
+);
+
+process.exit(result.status ?? 1);

package/scripts/setup-openclaw-workspace.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  buildAgentsContract,
+  buildSoulContract,
+  detectAgentsContract,
+  detectSoulContract,
+  normalizeRootName,
+  resolveCanonicalRootPath,
+} from './workspace-contract.mjs';
+
+function parseArgs(argv) {
+  const options = {
+    workspace: path.resolve(process.cwd()),
+    canonicalRootName: 'memory',
+    createMemoryRoot: true,
+  };
+
+  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 === '--no-create-memory-root') {
+      options.createMemoryRoot = false;
+      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-setup [--workspace <dir>] [--canonical-root-name <name>] [--no-create-memory-root]',
+    '',
+    'Idempotently appends the required Timeline contract blocks to AGENTS.md and SOUL.md.',
+  ].join('\n'));
+}
+
+function readTextFile(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+}
+
+function ensureTrailingNewline(content) {
+  if (!content) return '';
+  return content.endsWith('\n') ? content : `${content}\n`;
+}
+
+function mergeSection(existingContent, sectionContent, predicate) {
+  if (predicate(existingContent)) {
+    return { changed: false, content: ensureTrailingNewline(existingContent) };
+  }
+
+  const prefix = existingContent.trimEnd();
+  const merged = prefix
+    ? `${prefix}\n\n${sectionContent}\n`
+    : `${sectionContent}\n`;
+  return { changed: true, content: merged };
+}
+
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+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 = readTextFile(agentsPath);
+  const soulContent = readTextFile(soulPath);
+
+  const agentsResult = mergeSection(
+    agentsContent,
+    buildAgentsContract(),
+    detectAgentsContract,
+  );
+  const soulResult = mergeSection(
+    soulContent,
+    buildSoulContract(),
+    detectSoulContract,
+  );
+
+  writeFile(agentsPath, agentsResult.content);
+  writeFile(soulPath, soulResult.content);
+
+  if (options.createMemoryRoot) {
+    fs.mkdirSync(canonicalRootPath, { recursive: true });
+  }
+
+  const updates = [
+    `${agentsResult.changed ? 'updated' : 'kept'} ${agentsPath}`,
+    `${soulResult.changed ? 'updated' : 'kept'} ${soulPath}`,
+    `${options.createMemoryRoot ? 'ensured' : 'skipped'} ${canonicalRootPath}`,
+  ];
+
+  console.log(updates.join('\n'));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}