feat: release v0.3.3 — Hermes adapter, context offload, core refactor

src/core/seed/input.ts

@@ -0,0 +1,492 @@
+/**
+ * Input loading, validation, normalization, and timestamp handling for the `seed` command.
+ *
+ * Responsibilities:
+ * 1. Load raw JSON from file
+ * 2. Detect Format A (`{ sessions: [...] }`) vs Format B (`[...]`)
+ * 3. Six-layer validation (file → top-level → session → round → message → timestamp consistency)
+ * 4. Normalize into NormalizedInput with auto-generated sessionIds
+ * 5. Timestamp all-or-none check + fill strategy
+ */
+
+import fs from "node:fs";
+import crypto from "node:crypto";
+import type {
+  RawSession,
+  FormatA,
+  ValidationError,
+  NormalizedInput,
+  NormalizedSession,
+  NormalizedRound,
+  NormalizedMessage,
+  SeedCommandOptions,
+} from "./types.js";
+
+// ============================
+// Public API
+// ============================
+
+export interface LoadAndValidateResult {
+  /** Normalized input ready for pipeline consumption. */
+  input: NormalizedInput;
+  /** Whether the user needs to confirm timestamp auto-fill. */
+  needsTimestampConfirmation: boolean;
+}
+
+/**
+ * Load, validate, and normalize seed input from a file.
+ *
+ * Throws on fatal validation errors with a human-readable message
+ * that includes all collected errors.
+ */
+export function loadAndValidateInput(
+  opts: Pick<SeedCommandOptions, "input" | "sessionKey" | "strictRoundRole">,
+): LoadAndValidateResult {
+  // Layer 1: File — read + parse
+  const raw = loadRawInput(opts.input);
+
+  // Layer 2: Top-level — detect A vs B
+  const sessions = extractSessions(raw);
+
+  // Layers 3-5: session / round / message validation
+  const errors: ValidationError[] = [];
+  validateSessions(sessions, opts.strictRoundRole, errors);
+
+  if (errors.length > 0) {
+    throw new SeedValidationError(errors);
+  }
+
+  // Layer 6: Timestamp consistency (all-have / all-missing / mixed → error)
+  const tsResult = checkTimestampConsistency(sessions);
+  if (tsResult.status === "mixed") {
+    throw new SeedValidationError([{
+      stage: "timestamp_consistency",
+      message:
+        "Timestamp consistency check failed: some messages have timestamps while others do not. " +
+        "All messages must either have timestamps or none must have timestamps.",
+    }]);
+  }
+
+  // Normalize
+  const normalized = normalizeSessions(sessions, opts.sessionKey);
+
+  return {
+    input: {
+      sessions: normalized.sessions,
+      totalRounds: normalized.totalRounds,
+      totalMessages: normalized.totalMessages,
+      hasTimestamps: tsResult.status === "all_present",
+    },
+    needsTimestampConfirmation: tsResult.status === "all_missing",
+  };
+}
+
+/**
+ * Validate and normalize seed input from an already-parsed JSON object.
+ *
+ * This is the gateway-friendly variant of `loadAndValidateInput` — it skips
+ * the file-system layer (Layer 1) and accepts the raw parsed body directly.
+ * Timestamps missing from all messages are auto-filled (no interactive
+ * confirmation needed in HTTP context).
+ *
+ * Throws `SeedValidationError` on validation failures.
+ */
+export function validateAndNormalizeRaw(
+  raw: unknown,
+  opts?: { sessionKey?: string; strictRoundRole?: boolean; autoFillTimestamps?: boolean },
+): NormalizedInput {
+  const strictRoundRole = opts?.strictRoundRole ?? false;
+  const autoFillTimestamps = opts?.autoFillTimestamps ?? true;
+
+  // Layer 2: Top-level — detect A vs B
+  const sessions = extractSessions(raw);
+
+  // Layers 3-5: session / round / message validation
+  const errors: ValidationError[] = [];
+  validateSessions(sessions, strictRoundRole, errors);
+
+  if (errors.length > 0) {
+    throw new SeedValidationError(errors);
+  }
+
+  // Layer 6: Timestamp consistency
+  const tsResult = checkTimestampConsistency(sessions);
+  if (tsResult.status === "mixed") {
+    throw new SeedValidationError([{
+      stage: "timestamp_consistency",
+      message:
+        "Timestamp consistency check failed: some messages have timestamps while others do not. " +
+        "All messages must either have timestamps or none must have timestamps.",
+    }]);
+  }
+
+  // Normalize
+  const normalized = normalizeSessions(sessions, opts?.sessionKey);
+
+  const input: NormalizedInput = {
+    sessions: normalized.sessions,
+    totalRounds: normalized.totalRounds,
+    totalMessages: normalized.totalMessages,
+    hasTimestamps: tsResult.status === "all_present",
+  };
+
+  // Auto-fill timestamps in HTTP context (no interactive prompt)
+  if (tsResult.status === "all_missing" && autoFillTimestamps) {
+    fillTimestamps(input);
+  }
+
+  return input;
+}
+
+/**
+ * Fill timestamps for all messages when the input has no timestamps.
+ *
+ * Uses a single monotonically increasing counter across ALL sessions
+ * to guarantee global timestamp ordering. This is critical when multiple
+ * sessions share the same sessionKey — the L0 capture cursor (advanced
+ * per-session) would filter out later sessions whose timestamps fall
+ * below the cursor if ordering were not globally monotonic.
+ */
+export function fillTimestamps(input: NormalizedInput): void {
+  let currentTs = Date.now();
+  for (const session of input.sessions) {
+    for (const round of session.rounds) {
+      for (let i = 0; i < round.messages.length; i++) {
+        // Small offset per message to maintain strict ordering
+        round.messages[i]!.timestamp = currentTs;
+        currentTs += 100;
+      }
+    }
+  }
+  input.hasTimestamps = true;
+}
+
+// ============================
+// Validation error class
+// ============================
+
+export class SeedValidationError extends Error {
+  public readonly errors: ValidationError[];
+
+  constructor(errors: ValidationError[]) {
+    const summary = errors.map((e) => formatValidationError(e)).join("\n");
+    super(`Seed input validation failed (${errors.length} error(s)):\n${summary}`);
+    this.name = "SeedValidationError";
+    this.errors = errors;
+  }
+}
+
+function formatValidationError(e: ValidationError): string {
+  const parts: string[] = [`  [${e.stage}]`];
+  if (e.sourceIndex != null) parts.push(`session[${e.sourceIndex}]`);
+  if (e.sessionKey) parts.push(`key="${e.sessionKey}"`);
+  if (e.roundIndex != null) parts.push(`round[${e.roundIndex}]`);
+  if (e.messageIndex != null) parts.push(`msg[${e.messageIndex}]`);
+  parts.push(e.message);
+  return parts.join(" ");
+}
+
+// ============================
+// Layer 1: File loading
+// ============================
+
+function loadRawInput(filePath: string): unknown {
+  if (!fs.existsSync(filePath)) {
+    throw new SeedValidationError([{
+      stage: "file",
+      message: `Input file not found: ${filePath}`,
+    }]);
+  }
+
+  const content = fs.readFileSync(filePath, "utf-8").trim();
+  if (!content) {
+    throw new SeedValidationError([{
+      stage: "file",
+      message: "Input file is empty.",
+    }]);
+  }
+
+  try {
+    return JSON.parse(content);
+  } catch (err) {
+    throw new SeedValidationError([{
+      stage: "file",
+      message: `JSON parse error: ${err instanceof Error ? err.message : String(err)}`,
+    }]);
+  }
+}
+
+// ============================
+// Layer 2: Top-level format detection
+// ============================
+
+function extractSessions(raw: unknown): RawSession[] {
+  // Format A: { sessions: [...] }
+  if (
+    raw != null &&
+    typeof raw === "object" &&
+    !Array.isArray(raw) &&
+    "sessions" in raw
+  ) {
+    const obj = raw as FormatA;
+    if (!Array.isArray(obj.sessions)) {
+      throw new SeedValidationError([{
+        stage: "top_level",
+        message: 'Format A detected but "sessions" is not an array.',
+      }]);
+    }
+    return obj.sessions;
+  }
+
+  // Format B: [...]
+  if (Array.isArray(raw)) {
+    return raw as RawSession[];
+  }
+
+  throw new SeedValidationError([{
+    stage: "top_level",
+    message:
+      "Unrecognized input format. Expected either:\n" +
+      '  Format A: { "sessions": [...] }\n' +
+      "  Format B: [ { sessionKey, conversations }, ... ]",
+  }]);
+}
+
+// ============================
+// Layers 3-5: session / round / message validation
+// ============================
+
+function validateSessions(
+  sessions: RawSession[],
+  strictRoundRole: boolean,
+  errors: ValidationError[],
+): void {
+  if (sessions.length === 0) {
+    errors.push({
+      stage: "session",
+      message: "No sessions found in input.",
+    });
+    return;
+  }
+
+  for (let si = 0; si < sessions.length; si++) {
+    const session = sessions[si]!;
+
+    // Layer 3: session validation
+    if (!session.sessionKey || typeof session.sessionKey !== "string" || session.sessionKey.trim() === "") {
+      errors.push({
+        stage: "session",
+        sourceIndex: si,
+        message: '"sessionKey" is required and must be a non-empty string.',
+      });
+    }
+
+    if (!Array.isArray(session.conversations)) {
+      errors.push({
+        stage: "session",
+        sourceIndex: si,
+        sessionKey: session.sessionKey,
+        message: '"conversations" must be a two-dimensional array (array of rounds).',
+      });
+      continue; // Can't validate rounds
+    }
+
+    // Check that conversations is a 2D array
+    for (let ri = 0; ri < session.conversations.length; ri++) {
+      const round = session.conversations[ri];
+
+      // Layer 4: round validation
+      if (!Array.isArray(round)) {
+        errors.push({
+          stage: "round",
+          sourceIndex: si,
+          sessionKey: session.sessionKey,
+          roundIndex: ri,
+          message: "Round must be an array of messages.",
+        });
+        continue;
+      }
+
+      if (round.length === 0) {
+        errors.push({
+          stage: "round",
+          sourceIndex: si,
+          sessionKey: session.sessionKey,
+          roundIndex: ri,
+          message: "Round must be a non-empty array.",
+        });
+        continue;
+      }
+
+      // Strict round-role: each round must have at least one user and one assistant
+      if (strictRoundRole) {
+        const roles = new Set(round.map((m) => m.role));
+        if (!roles.has("user")) {
+          errors.push({
+            stage: "round",
+            sourceIndex: si,
+            sessionKey: session.sessionKey,
+            roundIndex: ri,
+            message: '--strict-round-role: round must contain at least one "user" message.',
+          });
+        }
+        if (!roles.has("assistant")) {
+          errors.push({
+            stage: "round",
+            sourceIndex: si,
+            sessionKey: session.sessionKey,
+            roundIndex: ri,
+            message: '--strict-round-role: round must contain at least one "assistant" message.',
+          });
+        }
+      }
+
+      // Layer 5: message validation
+      for (let mi = 0; mi < round.length; mi++) {
+        const msg = round[mi]!;
+
+        if (!msg.role || typeof msg.role !== "string") {
+          errors.push({
+            stage: "message",
+            sourceIndex: si,
+            sessionKey: session.sessionKey,
+            roundIndex: ri,
+            messageIndex: mi,
+            message: '"role" is required and must be a non-empty string.',
+          });
+        }
+
+        if (!msg.content || typeof msg.content !== "string" || msg.content.trim() === "") {
+          errors.push({
+            stage: "message",
+            sourceIndex: si,
+            sessionKey: session.sessionKey,
+            roundIndex: ri,
+            messageIndex: mi,
+            message: '"content" is required and must be a non-empty string.',
+          });
+        }
+
+        if (msg.timestamp !== undefined) {
+          if (typeof msg.timestamp === "number") {
+            if (!Number.isInteger(msg.timestamp)) {
+              errors.push({
+                stage: "message",
+                sourceIndex: si,
+                sessionKey: session.sessionKey,
+                roundIndex: ri,
+                messageIndex: mi,
+                message: '"timestamp" must be an integer (epoch milliseconds). Negative values are allowed for dates before 1970.',
+              });
+            }
+          } else if (typeof msg.timestamp === "string") {
+            if (Number.isNaN(new Date(msg.timestamp).getTime())) {
+              errors.push({
+                stage: "message",
+                sourceIndex: si,
+                sessionKey: session.sessionKey,
+                roundIndex: ri,
+                messageIndex: mi,
+                message: `"timestamp" string is not a valid ISO 8601 date: "${msg.timestamp}".`,
+              });
+            }
+          } else {
+            errors.push({
+              stage: "message",
+              sourceIndex: si,
+              sessionKey: session.sessionKey,
+              roundIndex: ri,
+              messageIndex: mi,
+              message: '"timestamp" must be a number (epoch ms) or an ISO 8601 string.',
+            });
+          }
+        }
+      }
+    }
+  }
+}
+
+// ============================
+// Layer 6: Timestamp consistency
+// ============================
+
+interface TimestampCheckResult {
+  status: "all_present" | "all_missing" | "mixed";
+}
+
+function checkTimestampConsistency(sessions: RawSession[]): TimestampCheckResult {
+  let hasTs = false;
+  let missingTs = false;
+
+  for (const session of sessions) {
+    if (!Array.isArray(session.conversations)) continue;
+    for (const round of session.conversations) {
+      if (!Array.isArray(round)) continue;
+      for (const msg of round) {
+        if (msg.timestamp !== undefined && msg.timestamp !== null) {
+          hasTs = true;
+        } else {
+          missingTs = true;
+        }
+        // Early exit on mixed
+        if (hasTs && missingTs) {
+          return { status: "mixed" };
+        }
+      }
+    }
+  }
+
+  if (hasTs && !missingTs) return { status: "all_present" };
+  if (!hasTs && missingTs) return { status: "all_missing" };
+  // No messages at all — treat as all_missing (will be caught by session validation)
+  return { status: "all_missing" };
+}
+
+// ============================
+// Normalization
+// ============================
+
+function normalizeSessions(
+  sessions: RawSession[],
+  fallbackSessionKey?: string,
+): { sessions: NormalizedSession[]; totalRounds: number; totalMessages: number } {
+  const normalized: NormalizedSession[] = [];
+  let totalRounds = 0;
+  let totalMessages = 0;
+
+  for (let si = 0; si < sessions.length; si++) {
+    const raw = sessions[si]!;
+
+    const sessionKey = raw.sessionKey || fallbackSessionKey || "seed-user";
+    const sessionId = raw.sessionId || crypto.randomUUID();
+
+    const rounds: NormalizedRound[] = [];
+    for (const rawRound of raw.conversations) {
+      if (!Array.isArray(rawRound)) continue;
+
+      const messages: NormalizedMessage[] = rawRound.map((msg) => ({
+        role: msg.role,
+        content: msg.content,
+        // Normalize timestamp: ISO string → epoch ms, number → pass-through, missing → 0 (filled later)
+        timestamp: msg.timestamp == null
+          ? 0
+          : typeof msg.timestamp === "string"
+            ? new Date(msg.timestamp).getTime()
+            : msg.timestamp,
+      }));
+
+      rounds.push({ messages });
+      totalMessages += messages.length;
+    }
+
+    totalRounds += rounds.length;
+    normalized.push({
+      sessionKey,
+      sessionId,
+      rounds,
+      sourceIndex: si,
+    });
+  }
+
+  return { sessions: normalized, totalRounds, totalMessages };
+}

src/core/seed/seed-runtime.ts

@@ -0,0 +1,421 @@
+/**
+ * Seed runtime: L0→L1→L2→L3 orchestration for the `seed` command.
+ *
+ * Uses the shared pipeline-factory for VectorStore/EmbeddingService init,
+ * L1 runner, L2 runner, L3 runner, and persister wiring — keeping this
+ * module focused on seed-specific concerns:
+ * - Synchronous per-round L0 capture with progress reporting
+ * - waitForL1Idle polling (L1 only — see FIXME below)
+ * - Ctrl+C graceful shutdown
+ *
+ * FIXME: Currently we only wait for L1 to become idle before destroying the
+ * pipeline.  L2 (scene extraction) and L3 (persona generation) may still be
+ * in-flight when `pipeline.destroy()` is called.  This is intentional for now
+ * to avoid excessively long seed runs, but means seed output may not include
+ * the latest L2/L3 artifacts.  Re-evaluate adding a full L1+L2+L3 idle wait
+ * once pipeline-manager exposes reliable L2/L3 idle signals.
+ */
+
+import path from "node:path";
+import { parseConfig } from "../../config.js";
+import type { MemoryTdaiConfig } from "../../config.js";
+import { performAutoCapture } from "../hooks/auto-capture.js";
+import { createPipeline, createL2Runner, createL3Runner } from "../../utils/pipeline-factory.js";
+import type { PipelineInstance, PipelineLogger } from "../../utils/pipeline-factory.js";
+import { readManifest, writeManifest } from "../../utils/manifest.js";
+import { StandaloneLLMRunnerFactory } from "../../adapters/standalone/llm-runner.js";
+import type { MemoryPipelineManager } from "../../utils/pipeline-manager.js";
+import type { LLMRunner } from "../types.js";
+import type {
+  NormalizedInput,
+  SeedProgress,
+  SeedSummary,
+} from "./types.js";
+
+const TAG = "[memory-tdai] [seed]";
+
+// ============================
+// Seed pipeline options
+// ============================
+
+export interface SeedRuntimeOptions {
+  /** Directory to store all seed output (L0, checkpoint, vectors.db). */
+  outputDir: string;
+  /** OpenClaw config object (needed for LLM calls in L1). */
+  openclawConfig: unknown;
+  /** Raw plugin config (same shape as api.pluginConfig). */
+  pluginConfig?: Record<string, unknown>;
+  /** Original input file path (for manifest traceability). */
+  inputFile?: string;
+  /** Logger instance. */
+  logger: PipelineLogger;
+  /** Progress callback (called after each round). */
+  onProgress?: (progress: SeedProgress) => void;
+}
+
+// ============================
+// Seed pipeline creation
+// ============================
+
+/**
+ * Create a seed pipeline using the shared factory, with L2/L3 runners
+ * wired via shared factory functions (same logic as index.ts live runtime).
+ */
+async function createSeedPipeline(opts: SeedRuntimeOptions): Promise<{ pipeline: PipelineInstance; cfg: MemoryTdaiConfig }> {
+  const { outputDir, openclawConfig, pluginConfig, logger } = opts;
+
+  // Parse config — all values come from pluginConfig (or parseConfig defaults)
+  const cfg = parseConfig(pluginConfig);
+
+  logger.info(
+    `${TAG} Creating seed pipeline: outputDir=${outputDir}, ` +
+    `everyN=${cfg.pipeline.everyNConversations}, l1Idle=${cfg.pipeline.l1IdleTimeoutSeconds}s, ` +
+    `l2Delay=${cfg.pipeline.l2DelayAfterL1Seconds}s, l2Min=${cfg.pipeline.l2MinIntervalSeconds}s, l2Max=${cfg.pipeline.l2MaxIntervalSeconds}s`,
+  );
+
+  // Create standalone LLM runners if cfg.llm is configured.
+  // Seed always runs outside OpenClaw, so it needs standalone runners
+  // unless an explicit openclawConfig is provided (rare).
+  let l1LlmRunner: LLMRunner | undefined;
+  let l2l3LlmRunner: LLMRunner | undefined;
+
+  if (cfg.llm.enabled && cfg.llm.apiKey) {
+    const runnerFactory = new StandaloneLLMRunnerFactory({
+      config: {
+        baseUrl: cfg.llm.baseUrl,
+        apiKey: cfg.llm.apiKey,
+        model: cfg.llm.model,
+        maxTokens: cfg.llm.maxTokens,
+        timeoutMs: cfg.llm.timeoutMs,
+      },
+      logger,
+    });
+    l1LlmRunner = runnerFactory.createRunner({ enableTools: false });
+    l2l3LlmRunner = runnerFactory.createRunner({ enableTools: true });
+    logger.info(`${TAG} Seed using standalone LLM: model=${cfg.llm.model}`);
+  }
+
+  // Use shared factory for everything: store init, L1 runner, persister, destroy
+  const pipeline = await createPipeline({
+    pluginDataDir: outputDir,
+    cfg,
+    openclawConfig,
+    logger,
+    l1LlmRunner,
+  });
+
+  // Wire L2 runner via shared factory (same logic as index.ts live runtime)
+  pipeline.scheduler.setL2Runner(createL2Runner({
+    pluginDataDir: outputDir,
+    cfg,
+    openclawConfig,
+    vectorStore: pipeline.vectorStore,
+    logger,
+    llmRunner: l2l3LlmRunner,
+  }));
+
+  // Wire L3 runner via shared factory (same logic as index.ts live runtime)
+  pipeline.scheduler.setL3Runner(createL3Runner({
+    pluginDataDir: outputDir,
+    cfg,
+    openclawConfig,
+    vectorStore: pipeline.vectorStore,
+    logger,
+    llmRunner: l2l3LlmRunner,
+  }));
+
+  return { pipeline, cfg };
+}
+
+// ============================
+// waitForL1Idle
+// ============================
+
+/**
+ * Poll pipeline queue status until L1 is idle for a given session.
+ * Modeled after benchmark-ingest.ts waitForPipelineIdle() but focused on L1 only.
+ */
+async function waitForL1Idle(
+  scheduler: MemoryPipelineManager,
+  sessionKeys: string[],
+  logger: PipelineLogger,
+  opts: {
+    pollIntervalMs?: number;
+    stableRounds?: number;
+    maxWaitMs?: number;
+  } = {},
+): Promise<void> {
+  const pollInterval = opts.pollIntervalMs ?? 1_000;
+  const stableRounds = opts.stableRounds ?? 3;
+  const maxWait = opts.maxWaitMs ?? 300_000; // 5 min default
+
+  const startTime = Date.now();
+  let consecutiveIdle = 0;
+
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed > maxWait) {
+      logger.warn(`${TAG} [waitL1] Max wait time reached (${(maxWait / 1000).toFixed(0)}s), proceeding`);
+      break;
+    }
+
+    const queues = scheduler.getQueueSizes();
+
+    // Check per-session: buffered messages + conversation count
+    let totalBuffered = 0;
+    let totalConversationCount = 0;
+    for (const key of sessionKeys) {
+      totalBuffered += scheduler.getBufferedMessageCount(key);
+      const state = scheduler.getSessionState(key);
+      if (state) {
+        totalConversationCount += state.conversation_count;
+      }
+    }
+
+    const isIdle =
+      queues.l1Idle &&
+      totalBuffered === 0 &&
+      totalConversationCount === 0;
+
+    if (isIdle) {
+      consecutiveIdle++;
+      if (consecutiveIdle >= stableRounds) {
+        logger.debug?.(`${TAG} [waitL1] L1 stable for ${stableRounds} consecutive polls`);
+        return;
+      }
+    } else {
+      consecutiveIdle = 0;
+      logger.debug?.(
+        `${TAG} [waitL1] Waiting: l1Queue=${queues.l1}, l1Pending=${queues.l1Pending}, l1Idle=${queues.l1Idle}, ` +
+        `buffered=${totalBuffered}, convCount=${totalConversationCount}`,
+      );
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+}
+
+// ============================
+// Main execution function
+// ============================
+
+/**
+ * Execute the seed pipeline: feed normalized input through L0 → L1.
+ *
+ * L2/L3 runners are wired but their completion is **not** awaited — see the
+ * module-level FIXME.  The pipeline is destroyed after L1 idle, so L2/L3 may
+ * be interrupted mid-run.
+ *
+ * This is the core runtime called by `src/cli/commands/seed.ts` after
+ * all input validation and user confirmation are complete.
+ */
+export async function executeSeed(
+  input: NormalizedInput,
+  opts: SeedRuntimeOptions,
+): Promise<SeedSummary> {
+  const { logger, onProgress } = opts;
+  const startTime = Date.now();
+
+  // Track interrupt signal
+  let interrupted = false;
+  const onSigint = () => {
+    if (interrupted) {
+      // Second Ctrl+C — force exit
+      logger.warn(`${TAG} Force exit (second Ctrl+C)`);
+      process.exit(1);
+    }
+    interrupted = true;
+    logger.warn(`${TAG} Interrupt received, finishing current round and shutting down...`);
+  };
+  process.on("SIGINT", onSigint);
+
+  let pipeline: PipelineInstance | undefined;
+  let totalL0Recorded = 0;
+  let roundsProcessed = 0;
+
+  try {
+    // Create and start pipeline (returns both the pipeline instance and the
+    // seed-optimized config so we don't need to parse config again)
+    const seed = await createSeedPipeline(opts);
+    pipeline = seed.pipeline;
+    const seedCfg = seed.cfg;
+
+    pipeline.scheduler.start({});
+    logger.info(`${TAG} Pipeline started, processing ${input.sessions.length} session(s), ${input.totalRounds} round(s)`);
+
+    // Seed-specific: use 0 so the cold-start guard in captureAtomically()
+    // does NOT filter out historical messages. In live mode Date.now()
+    // prevents the first agent_end from dumping full session history,
+    // but seed intentionally feeds all historical data.
+    const captureStartTimestamp = 0;
+
+    // Process each session → each round
+    // Key invariant: after every everyNConversations rounds we must wait for L1
+    // to finish before feeding more rounds. Without this pause the for-loop
+    // would dump all rounds into L0 back-to-back and L1 would only run once
+    // with the full batch (defeating the "every N" batching semantics).
+    const everyN = seedCfg.pipeline.everyNConversations;
+
+    for (const session of input.sessions) {
+      if (interrupted) break;
+
+      logger.info(`${TAG} Session: key="${session.sessionKey}" id="${session.sessionId}" rounds=${session.rounds.length}`);
+
+      for (let ri = 0; ri < session.rounds.length; ri++) {
+        if (interrupted) break;
+
+        const round = session.rounds[ri]!;
+        roundsProcessed++;
+
+        // Build messages in the format expected by performAutoCapture.
+        // Field must be named "timestamp" (not "ts") because l0-recorder's
+        // extractUserAssistantMessages reads m.timestamp for incremental filtering.
+        const messages = round.messages.map((m) => ({
+          role: m.role,
+          content: m.content,
+          timestamp: m.timestamp,
+        }));
+
+        try {
+          const result = await performAutoCapture({
+            messages,
+            sessionKey: session.sessionKey,
+            sessionId: session.sessionId,
+            cfg: seedCfg,
+            pluginDataDir: opts.outputDir,
+            logger,
+            scheduler: pipeline.scheduler,
+            pluginStartTimestamp: captureStartTimestamp,
+            vectorStore: pipeline.vectorStore,
+            embeddingService: pipeline.embeddingService,
+          });
+
+          totalL0Recorded += result.l0RecordedCount;
+        } catch (err) {
+          logger.error(
+            `${TAG} L0 capture failed for session="${session.sessionKey}" round=${ri}: ` +
+            `${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+
+        // Report progress
+        onProgress?.({
+          currentRound: roundsProcessed,
+          totalRounds: input.totalRounds,
+          sessionKey: session.sessionKey,
+          stage: "l0_captured",
+        });
+
+        // After every N rounds, wait for the triggered L1 to finish before
+        // feeding the next batch. This keeps L1 batches aligned with the
+        // everyNConversations boundary instead of letting all rounds pile up.
+        const roundInSession = ri + 1; // 1-based
+        if (roundInSession % everyN === 0 && !interrupted) {
+          onProgress?.({
+            currentRound: roundsProcessed,
+            totalRounds: input.totalRounds,
+            sessionKey: session.sessionKey,
+            stage: "l1_waiting",
+          });
+
+          logger.info(
+            `${TAG} Pausing after round ${roundInSession}/${session.rounds.length} ` +
+            `for session="${session.sessionKey}" — waiting for L1 to drain`,
+          );
+
+          await waitForL1Idle(
+            pipeline.scheduler,
+            [session.sessionKey],
+            logger,
+            { pollIntervalMs: 500, stableRounds: 2, maxWaitMs: 120_000 },
+          );
+        }
+      }
+
+      // After all rounds for this session, wait for any residual L1 work
+      // (handles the tail when total rounds is not a multiple of everyN)
+      if (!interrupted) {
+        onProgress?.({
+          currentRound: roundsProcessed,
+          totalRounds: input.totalRounds,
+          sessionKey: session.sessionKey,
+          stage: "l1_waiting",
+        });
+
+        await waitForL1Idle(
+          pipeline.scheduler,
+          [session.sessionKey],
+          logger,
+          { pollIntervalMs: 1_000, stableRounds: 3, maxWaitMs: 300_000 },
+        );
+
+        logger.info(`${TAG} L1 idle for session="${session.sessionKey}"`);
+      }
+    }
+
+    // Final wait for all sessions
+    if (!interrupted) {
+      const allKeys = input.sessions.map((s) => s.sessionKey);
+      logger.info(`${TAG} Final L1 idle wait for all sessions...`);
+      await waitForL1Idle(
+        pipeline.scheduler,
+        allKeys,
+        logger,
+        { pollIntervalMs: 1_000, stableRounds: 3, maxWaitMs: 300_000 },
+      );
+    }
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+
+    // Graceful shutdown
+    if (pipeline) {
+      try {
+        await pipeline.destroy();
+      } catch (err) {
+        logger.error(`${TAG} Pipeline destroy error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+
+  const durationMs = Date.now() - startTime;
+
+  const summary: SeedSummary = {
+    sessionsProcessed: input.sessions.length,
+    roundsProcessed,
+    messagesProcessed: input.totalMessages,
+    l0RecordedCount: totalL0Recorded,
+    durationMs,
+    outputDir: opts.outputDir,
+  };
+
+  if (interrupted) {
+    logger.warn(`${TAG} Seed interrupted after ${roundsProcessed}/${input.totalRounds} rounds`);
+  } else {
+    logger.info(
+      `${TAG} Seed complete: sessions=${summary.sessionsProcessed}, ` +
+      `rounds=${summary.roundsProcessed}, messages=${summary.messagesProcessed}, ` +
+      `l0Recorded=${summary.l0RecordedCount}, duration=${(durationMs / 1000).toFixed(1)}s`,
+    );
+  }
+
+  // Append seed info to manifest (non-fatal if it fails)
+  try {
+    const manifest = readManifest(opts.outputDir);
+    if (manifest) {
+      manifest.seed = {
+        inputFile: opts.inputFile ? path.basename(opts.inputFile) : undefined,
+        sessions: summary.sessionsProcessed,
+        rounds: summary.roundsProcessed,
+        messages: summary.messagesProcessed,
+        startedAt: new Date(startTime).toISOString(),
+        completedAt: new Date().toISOString(),
+      };
+      writeManifest(opts.outputDir, manifest);
+      logger.info(`${TAG} Manifest updated with seed info`);
+    }
+  } catch (err) {
+    logger.warn(`${TAG} Failed to update manifest with seed info (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return summary;
+}

src/core/seed/types.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared type definitions for the `seed` command.
+ *
+ * Covers:
+ * - Raw input shapes (Format A / B / JSONL)
+ * - Normalized internal structures
+ * - Validation error descriptors
+ */
+
+// ============================
+// Raw input types (before validation)
+// ============================
+
+/** A single message in a conversation round. */
+export interface RawMessage {
+  role: string;
+  content: string;
+  /**
+   * Epoch milliseconds (number) **or** ISO 8601 string (e.g. `"2024-04-01T12:00:00Z"`).
+   * ISO strings are parsed via `new Date()` during normalization and
+   * stored internally as epoch ms.
+   */
+  timestamp?: number | string;
+}
+
+/** A single session entry (shared between Format A wrapper and Format B array). */
+export interface RawSession {
+  sessionKey: string;
+  sessionId?: string;
+  conversations: RawMessage[][];
+}
+
+/** Format A: `{ sessions: [...] }` */
+export interface FormatA {
+  sessions: RawSession[];
+}
+
+/** Format B: `[...]` (top-level array of sessions) */
+export type FormatB = RawSession[];
+
+// ============================
+// Normalized types (after validation)
+// ============================
+
+export interface NormalizedMessage {
+  role: string;
+  content: string;
+  /** Epoch ms — always present after normalization (filled if originally missing). */
+  timestamp: number;
+}
+
+export interface NormalizedRound {
+  messages: NormalizedMessage[];
+}
+
+export interface NormalizedSession {
+  sessionKey: string;
+  sessionId: string;
+  rounds: NormalizedRound[];
+  /** Index in the original input array (for progress reporting). */
+  sourceIndex: number;
+}
+
+export interface NormalizedInput {
+  sessions: NormalizedSession[];
+  /** Total number of rounds across all sessions. */
+  totalRounds: number;
+  /** Total number of messages across all sessions. */
+  totalMessages: number;
+  /** Whether timestamps were present in the original input. */
+  hasTimestamps: boolean;
+}
+
+// ============================
+// Validation
+// ============================
+
+/** Stages where a validation error can occur. */
+export type ValidationStage =
+  | "file"
+  | "top_level"
+  | "session"
+  | "round"
+  | "message"
+  | "timestamp_consistency";
+
+/** A single validation error with location context. */
+export interface ValidationError {
+  stage: ValidationStage;
+  sourceIndex?: number;
+  sessionKey?: string;
+  roundIndex?: number;
+  messageIndex?: number;
+  message: string;
+}
+
+// ============================
+// Seed command options (from CLI)
+// ============================
+
+export interface SeedCommandOptions {
+  /** Path to input file (required). */
+  input: string;
+  /** Output directory (optional, auto-generated if missing). */
+  outputDir?: string;
+  /** Fallback session key when input lacks one. */
+  sessionKey?: string;
+  /** Strict round-role validation (each round must have user + assistant). */
+  strictRoundRole: boolean;
+  /** Skip interactive confirmations. */
+  yes: boolean;
+  /** Path to memory-tdai config override file (JSON, deep-merged on top of current plugin config). */
+  configFile?: string;
+}
+
+// ============================
+// Seed runtime types
+// ============================
+
+/** Progress info emitted during seed execution. */
+export interface SeedProgress {
+  /** Current round index (1-based, across all sessions). */
+  currentRound: number;
+  /** Total rounds. */
+  totalRounds: number;
+  /** Current session key. */
+  sessionKey: string;
+  /** Current stage description. */
+  stage: string;
+}
+
+/** Final summary after seed completes. */
+export interface SeedSummary {
+  sessionsProcessed: number;
+  roundsProcessed: number;
+  messagesProcessed: number;
+  l0RecordedCount: number;
+  durationMs: number;
+  outputDir: string;
+}