@jpssff/vanor 0.1.0

package/base/core/harness.js

@@ -0,0 +1,246 @@
+// AgentHarness：编排会话、phase、配置快照，串联 LLM / 工具 / 记忆 / 技能。
+
+import fs from "node:fs";
+import { createLLM } from "../llm/index.js";
+import { createSecurity } from "../security/index.js";
+import { createMemory } from "../memory/index.js";
+import { loadConfig, saveUiLanguage, startupIssues } from "../config.js";
+import { createI18n, isSupportedLanguageSetting } from "../i18n/index.js";
+import { EVENTS } from "../events.js";
+import { createSkillsTool, loadSkills, defaultSkillDirs } from "../skills/loader.js";
+import { defaultRegistry, createToolContext } from "../tools/index.js";
+import { userMessage } from "../transport/message.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { latestSession, saveLatestSessionId, Session } from "./session.js";
+import { runLoop } from "./loop.js";
+import { compact } from "./compaction.js";
+
+export function createHarness({ config, paths, logger, channel = "cli", sessionId, restoreLatest = false }) {
+  let configState = config;
+  let i18n = createI18n(configState);
+  let security = createSecurity({ ...configState, i18n });
+  let llm = createLLM(configState, logger);
+  let memory = createMemory(paths, configState, logger);
+  let registry;
+  let skills = [];
+  let configMtime = configFileMtime();
+
+  function configFileMtime() {
+    try {
+      return fs.statSync(paths.config).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  function skillDirs() {
+    return defaultSkillDirs(paths, security.workspaceRoot);
+  }
+  function reloadSkills() {
+    skills = loadSkills(skillDirs(), logger);
+    return skills;
+  }
+
+  function rebuildRuntime(nextConfig) {
+    configState = nextConfig;
+    i18n = createI18n(configState);
+    security = createSecurity({ ...configState, i18n });
+    llm = createLLM(configState, logger);
+    memory = createMemory(paths, configState, logger);
+    registry = defaultRegistry(i18n);
+    registry.register(memory.tool);
+    registry.register(createSkillsTool(paths, logger, { getSkills: () => skills, reloadSkills, getI18n: () => i18n }));
+    reloadSkills();
+  }
+
+  rebuildRuntime(configState);
+
+  let model = configState.llm.defaultModel;
+  let phase = "idle";
+  let restored = false;
+  let requestedSessionId = sessionId;
+  const sessionPaths = () => ({ ...paths, workspaceRoot: security.workspaceRoot });
+  if (!requestedSessionId && restoreLatest) requestedSessionId = latestSession(paths, security.workspaceRoot)?.id;
+
+  let session = requestedSessionId ? Session.load(sessionPaths(), logger, requestedSessionId) : null;
+  if (session) {
+    restored = true;
+    if (!session.model) session.model = model;
+    model = session.model || model;
+    session.resume();
+  } else {
+    session = new Session(sessionPaths(), logger, { model }).start();
+  }
+
+  function reloadConfig({ force = false } = {}) {
+    const mtime = configFileMtime();
+    if (!force && mtime === configMtime) return { reloaded: false, reason: "unchanged" };
+
+    const { config: nextConfig } = loadConfig(paths.config);
+    const nextI18n = createI18n(nextConfig);
+    const issues = startupIssues(nextConfig, nextI18n.t);
+    if (issues.length) {
+      return { reloaded: false, error: nextI18n.t("config.errors.invalidConfig", { issues: issues.join("; ") }), issues };
+    }
+
+    const previousDefault = configState.llm?.defaultModel;
+    const nextDefault = nextConfig.llm?.defaultModel;
+    rebuildRuntime(nextConfig);
+    configMtime = mtime;
+
+    let nextModel = model;
+    if (!nextModel || nextModel === previousDefault) nextModel = nextDefault;
+    try {
+      llm.resolveModel(nextModel);
+    } catch {
+      nextModel = nextDefault;
+    }
+    if (nextModel && nextModel !== model) {
+      model = nextModel;
+      session.setModel(model);
+    }
+    logger?.info?.(EVENTS.config.change, { model, configPath: paths.config, hotReload: true });
+    return { reloaded: true, model, config: configState, i18n };
+  }
+
+  function buildSystem() {
+    reloadSkills();
+    return buildSystemPrompt({
+      memory,
+      skills,
+      summary: session.summary,
+      workspaceRoot: security.workspaceRoot,
+      channel,
+      i18n,
+      instance: {
+        model,
+        provider: model.includes("/") ? model.slice(0, model.indexOf("/")) : "",
+        language: i18n.language,
+        languageSource: i18n.source,
+        languageConfigured: i18n.configured,
+        configPath: paths.config,
+        paths,
+        sessionId: session.id,
+        sessionRestored: restored,
+        approval: security.approval,
+        skillDirs: skillDirs(),
+        skillsCount: skills.length,
+      },
+    });
+  }
+
+  /**
+   * 运行一轮对话。
+   * @param {string} userText
+   * @param {object} handlers  { onText, onAssistant, onToolCalls, onToolResult, onUsage, onError, confirm }
+   * @param {AbortSignal} [signal]
+   */
+  async function runTurn(userText, handlers = {}, signal) {
+    if (phase !== "idle") throw new Error(i18n.t("harness.busy", { phase }));
+    phase = "turn";
+    try {
+      const reload = reloadConfig();
+      if (reload.error) handlers.onError?.(new Error(reload.error));
+      session.addMessage(userMessage(userText));
+      const toolCtx = createToolContext({
+        security,
+        logger,
+        signal,
+        confirm: handlers.confirm,
+        i18n,
+      });
+      const deps = {
+        llm,
+        registry,
+        toolCtx,
+        config: configState,
+        model,
+        tools: registry.schemas(),
+        buildSystem,
+        logger,
+      };
+      return await runLoop(session, deps, handlers, signal);
+    } finally {
+      phase = "idle";
+    }
+  }
+
+  function newSession() {
+    session = new Session(sessionPaths(), logger, { model }).start();
+    restored = false;
+    return session;
+  }
+
+  function setModel(m) {
+    llm.resolveModel(m); // 非法则抛错
+    model = m;
+    session.setModel(model);
+    return model;
+  }
+
+  function setLanguage(language) {
+    if (!isSupportedLanguageSetting(language)) {
+      throw new Error(i18n.t("cli.language.invalid", { language }));
+    }
+    saveUiLanguage(paths.config, language);
+    const result = reloadConfig({ force: true });
+    if (result.error) throw new Error(result.error);
+    return i18n;
+  }
+
+  async function compactNow() {
+    await compact(session, { llm, model, logger });
+  }
+
+  function saveState() {
+    saveLatestSessionId(paths, session.id, security.workspaceRoot);
+  }
+
+  return {
+    runTurn,
+    newSession,
+    setModel,
+    setLanguage,
+    compactNow,
+    saveState,
+    reloadConfig,
+    reloadSkills,
+    get model() {
+      return model;
+    },
+    get phase() {
+      return phase;
+    },
+    get session() {
+      return session;
+    },
+    get sessionRestored() {
+      return restored;
+    },
+    get memory() {
+      return memory;
+    },
+    get skills() {
+      return skills;
+    },
+    get registry() {
+      return registry;
+    },
+    get security() {
+      return security;
+    },
+    get i18n() {
+      return i18n;
+    },
+    get language() {
+      return i18n.language;
+    },
+    get llm() {
+      return llm;
+    },
+    get config() {
+      return configState;
+    },
+    paths,
+  };
+}

package/base/core/loop.js

@@ -0,0 +1,72 @@
+// AgentLoop：单轮内 LLM ↔ 工具的迭代循环。
+
+import { EVENTS } from "../events.js";
+import { assistantMessage } from "../transport/message.js";
+import { buildMessages } from "./prompt.js";
+import { runToolCalls } from "../tools/index.js";
+import { shouldCompact, compact } from "./compaction.js";
+
+/**
+ * 运行一轮对话直至无工具调用 / 达上限 / 中断 / 出错。
+ * @param {import('./session.js').Session} session
+ * @param {object} deps  { llm, registry, toolCtx, config, model, tools, buildSystem, logger }
+ * @param {object} handlers { onText, onAssistant, onToolCalls, onToolResult, onUsage, onError }
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<{assistant?, aborted?, error?, maxIterations?}>}
+ */
+export async function runLoop(session, deps, handlers = {}, signal) {
+  const { llm, registry, toolCtx, config, model, tools, buildSystem, logger } = deps;
+  const maxIter = config.agent?.maxIterations ?? 25;
+  logger.info(EVENTS.agent.turnStart, { model, sessionId: session.id });
+
+  for (let i = 0; i < maxIter; i++) {
+    if (signal?.aborted) {
+      logger.info(EVENTS.agent.turnAborted, { iteration: i });
+      return { aborted: true };
+    }
+
+    const messages = buildMessages(buildSystem(), session.messages);
+    let text = "";
+    const toolCalls = [];
+
+    try {
+      for await (const chunk of llm.stream({ model, messages, tools, signal })) {
+        if (chunk.type === "text") {
+          text += chunk.delta;
+          handlers.onText?.(chunk.delta);
+        } else if (chunk.type === "tool_call") {
+          toolCalls.push(chunk.call);
+        } else if (chunk.type === "usage") {
+          session.addUsage(chunk.usage);
+          handlers.onUsage?.(session.usage);
+        }
+      }
+    } catch (e) {
+      if (e.name === "AbortError") {
+        logger.info(EVENTS.agent.turnAborted, { iteration: i });
+        return { aborted: true };
+      }
+      logger.error(EVENTS.llm.error, { error: e.message });
+      handlers.onError?.(e);
+      return { error: e };
+    }
+
+    const assistant = assistantMessage(text, toolCalls);
+    session.addMessage(assistant);
+    handlers.onAssistant?.(assistant);
+
+    if (!toolCalls.length) {
+      logger.info(EVENTS.agent.turnEnd, { iterations: i + 1 });
+      return { assistant };
+    }
+
+    handlers.onToolCalls?.(toolCalls);
+    const results = await runToolCalls(toolCalls, registry, toolCtx, handlers.onToolResult);
+    for (const r of results) session.addMessage(r);
+
+    if (shouldCompact(session, config)) await compact(session, deps);
+  }
+
+  logger.warn(EVENTS.agent.turnMaxIterations, { maxIter });
+  return { maxIterations: true };
+}

package/base/core/prompt.js

@@ -0,0 +1,126 @@
+// 系统 prompt 组装：人设 + 环境 + 记忆快照 + 技能清单 + 历史摘要。
+
+import os from "node:os";
+import { createI18n } from "../i18n/index.js";
+import { nowIso } from "../utils.js";
+import { renderSkills } from "../skills/loader.js";
+import { systemMessage } from "../transport/message.js";
+
+const OS_NAMES = { darwin: "macOS", linux: "Linux", win32: "Windows" };
+
+/** 组装详细运行环境描述（含 Node.js 运行时信息）。 */
+function tzOffset() {
+  const offMin = -new Date().getTimezoneOffset(); // 东区为正
+  const sign = offMin >= 0 ? "+" : "-";
+  const abs = Math.abs(offMin);
+  return `UTC${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
+
+function timeZoneName() {
+  try {
+    return globalThis.Intl?.DateTimeFormat?.().resolvedOptions?.().timeZone || process.env.TZ || "Local";
+  } catch {
+    return process.env.TZ || "Local";
+  }
+}
+
+function runtimeEnv(workspaceRoot, t) {
+  const osName = OS_NAMES[process.platform] || process.platform;
+  const shell = process.env.SHELL || (process.platform === "win32" ? "powershell" : "sh");
+  const tz = timeZoneName();
+  return [
+    t("prompt.runtimeTitle"),
+    t("prompt.os", { name: osName, platform: process.platform, arch: process.arch, release: os.release() }),
+    t("prompt.node", { version: process.version }),
+    t("prompt.shell", { shell }),
+    t("prompt.workspace", { workspace: workspaceRoot }),
+    t("prompt.time", { time: nowIso(), timezone: tz, offset: tzOffset() }),
+  ].join("\n");
+}
+
+function providerName(model) {
+  const s = String(model || "");
+  const slash = s.indexOf("/");
+  return slash > 0 ? s.slice(0, slash) : "";
+}
+
+function vanorContext(ctx = {}, t) {
+  const lines = [t("prompt.contextTitle")];
+  if (ctx.model) lines.push(t("prompt.currentModel", { model: ctx.model }));
+  const provider = ctx.provider || providerName(ctx.model);
+  if (provider) lines.push(t("prompt.provider", { provider }));
+  if (ctx.language) {
+    lines.push(t("prompt.uiLanguage", { language: ctx.language, configured: ctx.languageConfigured || "auto", source: ctx.languageSource || "" }));
+  }
+  if (ctx.configPath) lines.push(t("prompt.configPath", { path: ctx.configPath }));
+  if (ctx.sessionId) {
+    lines.push(t("prompt.session", { id: ctx.sessionId, restored: ctx.sessionRestored ? t("prompt.restored") : "" }));
+  }
+  if (ctx.approval) lines.push(t("prompt.approval", { approval: ctx.approval }));
+  if (ctx.paths) {
+    const p = ctx.paths;
+    if (p.root) lines.push(t("prompt.runtimeRoot", { path: p.root }));
+    if (p.sessions) lines.push(t("prompt.sessionsDir", { path: p.sessions }));
+    if (p.memory) lines.push(t("prompt.memoryDir", { path: p.memory }));
+    if (p.skills) lines.push(t("prompt.localSkillsDir", { path: p.skills }));
+    if (p.logs) lines.push(t("prompt.logsDir", { path: p.logs }));
+  }
+  if (ctx.skillDirs?.length) lines.push(t("prompt.skillDirs", { dirs: ctx.skillDirs.join("; ") }));
+  if (Number.isFinite(ctx.skillsCount)) lines.push(t("prompt.skillsCount", { count: ctx.skillsCount }));
+  lines.push(t("prompt.answerContext"));
+  lines.push(t("prompt.noSecrets"));
+  return lines.join("\n");
+}
+
+/** 读取当前终端能力：宽度、行数、TERM 类型、颜色支持。 */
+function terminalInfo() {
+  return {
+    cols: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+    term: process.env.TERM || "unknown",
+    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+    trueColor: /truecolor|24bit/i.test(process.env.COLORTERM || ""),
+  };
+}
+
+/** 构造系统 prompt 文本。 */
+export function buildSystemPrompt({ memory, skills, summary, workspaceRoot, channel = "cli", terminal, instance, i18n, language }) {
+  const currentI18n = i18n || createI18n(language || "en");
+  const { t } = currentI18n;
+  const parts = [t("prompt.persona"), t("prompt.language")];
+  parts.push(runtimeEnv(workspaceRoot, t));
+  if (instance) parts.push(vanorContext(instance, t));
+  const guide = channel === "cli" ? t("prompt.channelCli") : t("prompt.channelDefault");
+  parts.push(t("prompt.communication", { guide }));
+
+  if (channel === "cli") {
+    const term = terminal || terminalInfo();
+    const color = term.color
+      ? currentI18n.t("prompt.colorSupported", { trueColor: term.trueColor ? currentI18n.t("prompt.trueColor") : "" })
+      : currentI18n.t("prompt.colorUnsupported");
+    parts.push(
+      currentI18n.t("prompt.terminal", {
+        term: term.term,
+        cols: term.cols,
+        rows: term.rows,
+        color,
+        ansi: term.color ? currentI18n.t("prompt.ansiHint") : "",
+      }),
+    );
+  }
+
+  const mem = memory.snapshot();
+  if (mem) parts.push(mem);
+
+  const sk = renderSkills(skills, currentI18n);
+  if (sk) parts.push(sk);
+
+  if (summary) parts.push(t("prompt.historySummary", { summary }));
+
+  return parts.join("\n\n");
+}
+
+/** 构造发往 LLM 的完整消息序列。 */
+export function buildMessages(systemText, sessionMessages) {
+  return [systemMessage(systemText), ...sessionMessages];
+}

package/base/core/session.js

@@ -0,0 +1,255 @@
+// 会话：运行时上下文（messages + summary + usage）与 JSONL 持久化。
+
+import fs from "node:fs";
+import path from "node:path";
+import { EVENTS } from "../events.js";
+import { ensureDir, genId, nowIso, readJsonSafe, writeJson } from "../utils.js";
+
+function parseJsonLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function trimIncompleteTail(messages) {
+  const out = [...messages];
+  for (;;) {
+    const last = out[out.length - 1];
+    if (!last) break;
+    if (last.role === "user") {
+      out.pop();
+      continue;
+    }
+    if (last.role === "assistant" && last.toolCalls?.length) {
+      out.pop();
+      continue;
+    }
+    if (last.role === "tool") {
+      while (out[out.length - 1]?.role === "tool") out.pop();
+      if (out[out.length - 1]?.role === "assistant" && out[out.length - 1]?.toolCalls?.length) out.pop();
+      continue;
+    }
+    break;
+  }
+  return out;
+}
+
+function stateFile(paths) {
+  if (paths.state) return paths.state;
+  if (paths.root) return path.join(paths.root, "state.json");
+  return null;
+}
+
+export function readSessionState(paths) {
+  const file = stateFile(paths);
+  return file ? readJsonSafe(file, {}) || {} : {};
+}
+
+export function writeSessionState(paths, patch) {
+  const file = stateFile(paths);
+  if (!file) return;
+  const prev = readSessionState(paths);
+  writeJson(file, { ...prev, ...patch, updatedAt: nowIso() });
+}
+
+export function saveLatestSessionId(paths, id, workspaceRoot) {
+  if (!id) return;
+  const patch = { latestSessionId: id };
+  if (workspaceRoot) {
+    const prev = readSessionState(paths);
+    patch.workspaces = {
+      ...(prev.workspaces || {}),
+      [workspaceRoot]: { latestSessionId: id, updatedAt: nowIso() },
+    };
+  }
+  writeSessionState(paths, patch);
+}
+
+export class Session {
+  constructor(paths, logger, { id, model } = {}) {
+    this.paths = paths;
+    this.logger = logger;
+    this.id = id || genId("sess");
+    this.model = model || "";
+    this.file = path.join(paths.sessions, `${this.id}.jsonl`);
+    this.messages = [];
+    this.summary = "";
+    this.usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    this.restored = false;
+    this.workspaceRoot = paths.workspaceRoot || "";
+  }
+
+  start() {
+    ensureDir(this.paths.sessions);
+    this._append({ type: "meta", ts: nowIso(), key: "start", value: { model: this.model } });
+    saveLatestSessionId(this.paths, this.id, this.workspaceRoot);
+    this.logger?.info(EVENTS.session.start, { id: this.id, model: this.model });
+    return this;
+  }
+
+  static load(paths, logger, id) {
+    if (!id) return null;
+    const file = path.join(paths.sessions, `${id}.jsonl`);
+    if (!fs.existsSync(file)) return null;
+
+    const session = new Session(paths, logger, { id });
+    session.file = file;
+    session.restored = true;
+
+    const text = fs.readFileSync(file, "utf8");
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      const entry = parseJsonLine(line);
+      if (!entry) continue; // 单行损坏不影响整体恢复
+
+      if (entry.type === "meta" && entry.key === "start") {
+        session.model = entry.value?.model || session.model;
+      } else if (entry.type === "meta" && entry.key === "model") {
+        session.model = entry.value?.model || entry.value || session.model;
+      } else if (entry.type === "message" && entry.message?.role) {
+        session.messages.push(entry.message);
+      } else if (entry.type === "compaction") {
+        if (entry.summary) session.summary = session.summary ? `${session.summary}\n${entry.summary}` : entry.summary;
+        const replaced = Number(entry.replaced || 0);
+        if (replaced > 0) session.messages = session.messages.slice(Math.min(replaced, session.messages.length));
+      } else if (entry.type === "usage") {
+        session.usage.promptTokens += entry.usage?.promptTokens || 0;
+        session.usage.completionTokens += entry.usage?.completionTokens || 0;
+        session.usage.totalTokens += entry.usage?.totalTokens || 0;
+      }
+    }
+
+    session.messages = trimIncompleteTail(session.messages);
+    return session;
+  }
+
+  resume() {
+    ensureDir(this.paths.sessions);
+    this._append({ type: "meta", ts: nowIso(), key: "resume", value: { model: this.model } });
+    saveLatestSessionId(this.paths, this.id, this.workspaceRoot);
+    this.logger?.info(EVENTS.session.resume, { id: this.id, model: this.model, messages: this.messages.length });
+    return this;
+  }
+
+  setModel(model) {
+    this.model = model || "";
+    this._append({ type: "meta", ts: nowIso(), key: "model", value: { model: this.model } });
+  }
+
+  _append(entry) {
+    try {
+      fs.appendFileSync(this.file, JSON.stringify(entry) + "\n");
+    } catch {
+      // 持久化失败不影响主流程
+    }
+  }
+
+  addMessage(message) {
+    this.messages.push(message);
+    this._append({ type: "message", ts: nowIso(), message });
+    return message;
+  }
+
+  addUsage(usage) {
+    if (!usage) return;
+    this.usage.promptTokens += usage.promptTokens || 0;
+    this.usage.completionTokens += usage.completionTokens || 0;
+    this.usage.totalTokens += usage.totalTokens || 0;
+    this._append({ type: "usage", ts: nowIso(), usage });
+  }
+
+  /** 估算当前上下文 token 数（约 4 字符 / token）。 */
+  estimatedTokens() {
+    let chars = this.summary.length;
+    for (const m of this.messages) {
+      chars += (m.content || "").length;
+      if (m.toolCalls) chars += JSON.stringify(m.toolCalls).length;
+    }
+    return Math.ceil(chars / 4);
+  }
+
+  /** compaction 后替换内存中的消息（磁盘历史保留）。 */
+  replaceRecent(recent) {
+    this.messages = recent;
+  }
+
+  addCompaction({ summary, replaced }) {
+    this._append({ type: "compaction", ts: nowIso(), summary, replaced });
+    this.logger?.info(EVENTS.session.compact, { id: this.id, replaced });
+  }
+}
+
+function sessionInfo(paths, id) {
+  if (!id) return null;
+  const file = path.join(paths.sessions, `${id}.jsonl`);
+  if (!fs.existsSync(file)) return null;
+  const stat = fs.statSync(file);
+  let model = "";
+  let messageCount = 0;
+  const text = fs.readFileSync(file, "utf8");
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    const e = parseJsonLine(line);
+    if (!e) continue;
+    if (e.type === "meta" && e.key === "start") model = e.value?.model || "";
+    if (e.type === "meta" && e.key === "model") model = e.value?.model || e.value || model;
+    if (e.type === "message") messageCount++;
+  }
+  return { id, file, model, messageCount, mtime: stat.mtimeMs };
+}
+
+/** 列出历史会话（用于 vanor sessions）。 */
+export function listSessions(paths) {
+  if (!fs.existsSync(paths.sessions)) return [];
+  return fs
+    .readdirSync(paths.sessions)
+    .filter((f) => f.endsWith(".jsonl"))
+    .map((f) => {
+      const file = path.join(paths.sessions, f);
+      const stat = fs.statSync(file);
+      let model = "";
+      let messageCount = 0;
+      const text = fs.readFileSync(file, "utf8");
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        const e = parseJsonLine(line);
+        if (!e) continue;
+        if (e.type === "meta" && e.key === "start") model = e.value?.model || "";
+        if (e.type === "message") messageCount++;
+      }
+      return { id: f.replace(/\.jsonl$/, ""), file, model, messageCount, mtime: stat.mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+}
+
+/** 列出某个会话中所有用户消息（从 JSONL 读取完整历史，不受内存 compaction 影响）。 */
+export function listUserMessages(paths, id) {
+  if (!id) return [];
+  const file = path.join(paths.sessions, `${id}.jsonl`);
+  if (!fs.existsSync(file)) return [];
+  const messages = [];
+  const text = fs.readFileSync(file, "utf8");
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    const entry = parseJsonLine(line);
+    if (entry?.type !== "message" || entry.message?.role !== "user") continue;
+    messages.push({
+      id: entry.message.id || "",
+      time: entry.message.meta?.timestamp || entry.ts || "",
+      content: entry.message.content || "",
+    });
+  }
+  return messages;
+}
+
+export function latestSession(paths, workspaceRoot) {
+  const state = readSessionState(paths);
+  const stateId = workspaceRoot
+    ? state.workspaces?.[workspaceRoot]?.latestSessionId || state.latestSessionId
+    : state.latestSessionId;
+  const fromState = sessionInfo(paths, stateId);
+  if (fromState) return fromState;
+  return listSessions(paths)[0] || null;
+}