mirror-mind 0.0.1 → 0.33.0

package/ts/src/conversation/sessionComposites.ts

@@ -0,0 +1,258 @@
+// Session lifecycle composites (CV22.DS7.US10 slice D).
+//
+// Ports `session_start`, `session_start_fast`, `session_maintenance`,
+// `close_stale_orphans`, `retitle_pending_conversations`, and
+// `_reset_session_orientation` from `src/memory/cli/conversation_logger.py`.
+//
+// These are the composites Pi runs at session boundaries, and their REPORT is
+// the user-visible surface: Pi prints it. Parity is therefore string-exact in
+// grammar, labels, order, and the warning tails — everything except the
+// elapsed seconds, which are wall-clock and cannot be byte-stable across runs
+// or cores.
+//
+// The clock is injected rather than read (Navigator decision 2, 2026-09-03):
+// tests pin durations, and cross-core comparison normalizes the timing token
+// only after validating its exact grammar, so a re-worded or re-punctuated
+// report still fails. Freezing real timings would have faked the evidence
+// instead of isolating it.
+
+import {
+  countCarriedOverConversations,
+  countConversationsWithExtractionStatus,
+  countQuarantinedConversations,
+  extractPending,
+} from "#conversation/extractionDriver.ts";
+import { setMute } from "#conversation/logger.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { GLOBAL_STICKY_DEFAULTS_SESSION_ID } from "#mirror/runtimeSession.ts";
+import { deactivateOperatingMode } from "#mode/operatingMode.ts";
+import { nowIso } from "#util/pyGenerators.ts";
+
+/** Python's `close_stale_orphans` default. */
+export const STALE_ORPHAN_THRESHOLD_MINUTES = 30;
+/** Python's `retitle_pending_conversations` default. */
+export const RETITLE_LIMIT = 5;
+
+export interface MaintenanceDeps {
+  /** Close one conversation through the full close tail. Throwing is isolated. */
+  closeConversation: (db: WritableDatabase, conversationId: string) => Promise<void> | void;
+  /** Improve one ended conversation's title; returns true when it changed. */
+  retitleConversation: (db: WritableDatabase, conversationId: string) => Promise<boolean> | boolean;
+  /** The DS5 orchestration behind replay with its accounting, as the driver injects it. */
+  runExtraction: (db: WritableDatabase, conversationId: string) => Promise<void> | void;
+  /**
+   * `backfillPiSessions` (slice E) bound to its resolved sessions directory.
+   * Injected rather than resolved here so the composite never reads the
+   * environment itself; the front door owns that resolution.
+   */
+  backfillPiSessions: (db: WritableDatabase) => Promise<number> | number;
+  /** Python's `MEMORY_MAINTENANCE_MAX_EXTRACTIONS` (AI-05); defaults to the released budget. */
+  extractionLimit?: number;
+  /** Monotonic seconds, injected so report timings are pinnable. */
+  monotonic?: () => number;
+  now?: () => string;
+}
+
+/**
+ * Python's `_reset_session_orientation`: a new runtime session starts from
+ * intention, not stale mode or journey context.
+ */
+export function resetSessionOrientation(db: WritableDatabase, now: () => string = nowIso): void {
+  deactivateOperatingMode(db, null, now());
+  db.prepare("DELETE FROM runtime_sessions WHERE session_id = ?").run(
+    GLOBAL_STICKY_DEFAULTS_SESSION_ID,
+  );
+}
+
+/** Conversation ids bound to an active runtime session. */
+function activeConversationIds(db: WritableDatabase): Set<string> {
+  const rows = db
+    .prepare(
+      "SELECT conversation_id FROM runtime_sessions WHERE active = 1 AND conversation_id IS NOT NULL",
+    )
+    .all() as Record<string, unknown>[];
+  return new Set(rows.map((row) => String(row.conversation_id)));
+}
+
+/** Python's `get_open_conversations_idle_since`. */
+function openConversationsIdleSince(db: WritableDatabase, threshold: string): string[] {
+  const rows = db
+    .prepare(
+      `SELECT c.id FROM conversations c
+        WHERE c.ended_at IS NULL
+          AND (
+            (SELECT MAX(m.created_at) FROM messages m WHERE m.conversation_id = c.id) < ?
+            OR NOT EXISTS (SELECT 1 FROM messages m WHERE m.conversation_id = c.id)
+          )`,
+    )
+    .all(threshold) as Record<string, unknown>[];
+  return rows.map((row) => String(row.id));
+}
+
+/**
+ * Python's `close_stale_orphans`: end open conversations idle longer than the
+ * threshold, skipping any still bound to an active runtime session.
+ *
+ * The count increments even when closing raises: `ended_at` is written before
+ * the tail, so the orphan IS closed and an extraction failure must not stop the
+ * loop or under-report the work. That asymmetry is deliberate in Python.
+ *
+ * KNOWN UNBOUNDED SPEND (registered for Debt Review): AI-05 caps extraction per
+ * maintenance run, but this loop has no cap on orphan count and each orphan
+ * runs the full close tail. Ported as-is; naming it here so DS8 prices it.
+ */
+export async function closeStaleOrphans(
+  db: WritableDatabase,
+  deps: Pick<MaintenanceDeps, "closeConversation" | "now"> & { thresholdMinutes?: number },
+): Promise<number> {
+  const thresholdMinutes = deps.thresholdMinutes ?? STALE_ORPHAN_THRESHOLD_MINUTES;
+  const now = deps.now ?? nowIso;
+  const threshold = new Date(Date.parse(now()) - thresholdMinutes * 60_000).toISOString();
+
+  const active = activeConversationIds(db);
+  let count = 0;
+  for (const conversationId of openConversationsIdleSince(db, threshold)) {
+    if (active.has(conversationId)) continue;
+    try {
+      await deps.closeConversation(db, conversationId);
+    } catch {
+      // The orphan is closed regardless; a failed tail must not stop the loop.
+    }
+    count += 1;
+  }
+  return count;
+}
+
+/**
+ * Python's `retitle_pending_conversations`: opportunistically improve a small
+ * batch of ended conversation titles at startup.
+ */
+export async function retitlePendingConversations(
+  db: WritableDatabase,
+  deps: Pick<MaintenanceDeps, "retitleConversation"> & { limit?: number },
+): Promise<number> {
+  const limit = deps.limit ?? RETITLE_LIMIT;
+  if (limit <= 0) return 0;
+
+  let candidates: string[];
+  try {
+    const scanLimit = Math.max(limit * 10, 50);
+    const rows = db
+      .prepare(
+        `SELECT c.id
+           FROM conversations c
+          WHERE c.ended_at IS NOT NULL
+            AND EXISTS (SELECT 1 FROM messages m WHERE m.conversation_id = c.id AND m.role = 'user')
+            AND EXISTS (SELECT 1 FROM messages m WHERE m.conversation_id = c.id AND m.role = 'assistant')
+          ORDER BY c.ended_at DESC, c.started_at DESC
+          LIMIT ?`,
+      )
+      .all(scanLimit) as Record<string, unknown>[];
+    candidates = rows.map((row) => String(row.id));
+  } catch {
+    return 0;
+  }
+
+  let changed = 0;
+  for (const conversationId of candidates) {
+    if (changed >= limit) break;
+    try {
+      if (await deps.retitleConversation(db, conversationId)) changed += 1;
+    } catch {
+      // Python swallows per-conversation failures and continues the batch.
+    }
+  }
+  return changed;
+}
+
+interface TimedStep {
+  label: string;
+  count: number;
+  elapsed: number;
+}
+
+async function timedStep(
+  label: string,
+  monotonic: () => number,
+  run: () => Promise<number> | number,
+): Promise<TimedStep> {
+  const started = monotonic();
+  const count = await run();
+  return { label, count, elapsed: monotonic() - started };
+}
+
+/** Python's `%.1f` seconds rendering inside the report. */
+function formatElapsed(elapsed: number): string {
+  return elapsed.toFixed(1);
+}
+
+/**
+ * Python's `session_maintenance`: four timed steps in a fixed order, then the
+ * warning tails. The step order is behavior, not presentation — closing stale
+ * orphans first is what makes their conversations eligible for the extraction
+ * step in the same run.
+ */
+export async function sessionMaintenance(
+  db: WritableDatabase,
+  deps: MaintenanceDeps,
+): Promise<string> {
+  const monotonic = deps.monotonic ?? (() => performance.now() / 1000);
+
+  const steps: TimedStep[] = [
+    await timedStep("Closed stale conversations", monotonic, () =>
+      closeStaleOrphans(db, {
+        closeConversation: deps.closeConversation,
+        now: deps.now,
+        thresholdMinutes: STALE_ORPHAN_THRESHOLD_MINUTES,
+      }),
+    ),
+    await timedStep("Backfilled Pi sessions", monotonic, () => deps.backfillPiSessions(db)),
+    await timedStep("Retitled pending conversations", monotonic, () =>
+      retitlePendingConversations(db, { retitleConversation: deps.retitleConversation }),
+    ),
+    await timedStep("Extracted pending conversations", monotonic, () =>
+      extractPending(db, { runExtraction: deps.runExtraction, limit: deps.extractionLimit }),
+    ),
+  ];
+
+  const parts = ["Conversation maintenance complete."];
+  for (const step of steps) {
+    parts.push(`${step.label}: ${step.count} (${formatElapsed(step.elapsed)}s)`);
+  }
+
+  const quarantined = countQuarantinedConversations(db);
+  if (quarantined) {
+    parts.push(`⚠ ${quarantined} conversation(s) quarantined after repeated extraction failure`);
+  }
+  const parseFailed = countConversationsWithExtractionStatus(db, "parse_failed");
+  if (parseFailed) {
+    parts.push(`⚠ ${parseFailed} conversation(s) with unreadable model output (parse_failed)`);
+  }
+  const carriedOver = countCarriedOverConversations(db);
+  if (carriedOver) {
+    parts.push(
+      `${carriedOver} conversation(s) carried over to the next run ` +
+        "(maintenance extraction budget)",
+    );
+  }
+  return parts.join("\n");
+}
+
+/** Python's `session_start_fast`: unmute and reorient, defer the expensive work. */
+export function sessionStartFast(db: WritableDatabase, mirrorHome: string, now = nowIso): string {
+  setMute(false, mirrorHome);
+  resetSessionOrientation(db, now);
+  return "Conversation logging ACTIVE. Maintenance deferred.";
+}
+
+/** Python's `session_start`: unmute, reorient, then run full maintenance. */
+export async function sessionStart(
+  db: WritableDatabase,
+  mirrorHome: string,
+  deps: MaintenanceDeps,
+): Promise<string> {
+  setMute(false, mirrorHome);
+  resetSessionOrientation(db, deps.now ?? nowIso);
+  const maintenance = await sessionMaintenance(db, deps);
+  return ["Conversation logging ACTIVE.", maintenance].join("\n");
+}

package/ts/src/conversation/sessionImport.ts

@@ -0,0 +1,90 @@
+// Atomic closed-session import (CV22.DS7.US10 slice E).
+//
+// Ports `RuntimeSessionService.import_closed_conversation` from
+// `src/memory/services/runtime_session.py`, the seam both backfills write
+// through. It is the sibling of `getOrCreateSessionConversation` in
+// `logger.ts` and shares its transaction discipline for the same reason:
+// a backfill imports against the SAME `runtime_sessions` key a live hook
+// binds (Pi's live session id is the session file path), and the two can
+// interleave.
+//
+// Resolved decision 4B (plan.md): the binding check runs INSIDE the
+// `BEGIN IMMEDIATE` transaction, so a binding a concurrent hook committed
+// while this import waited for the write lock is seen and honored -- the
+// import returns null instead of clobbering a live session with
+// `active=0`/`closed_at`. The same atomicity removes the crash-window
+// duplicate-import path: either the conversation, every message, and the
+// binding all land, or nothing does.
+//
+// Titles are deliberately NOT set here. The two callers title differently
+// (Pi through `setProvisionalTitle`, Codex through a bare column write) and
+// Python applies both after commit; reproducing that asymmetry is the
+// callers' job.
+
+import type { LoggerDeps } from "#conversation/logger.ts";
+import { type WritableDatabase, withTransaction } from "#db/database.ts";
+
+export interface ImportedMessage {
+  role: string;
+  content: string;
+  createdAt: string;
+}
+
+export interface ClosedSessionImport {
+  interface: string;
+  messages: readonly ImportedMessage[];
+  endedAt: string;
+}
+
+/**
+ * Import a closed session transcript as one conversation bound to
+ * `sessionId`. Returns the new conversation id, or null when the session is
+ * already tracked -- including by a writer that won the binding while this
+ * call waited for the lock.
+ */
+export function importClosedConversation(
+  db: WritableDatabase,
+  sessionId: string,
+  session: ClosedSessionImport,
+  deps: LoggerDeps,
+): string | null {
+  return withTransaction(db, () => {
+    const tracked = db
+      .prepare("SELECT 1 FROM runtime_sessions WHERE session_id = ?")
+      .get(sessionId);
+    if (tracked) return null;
+
+    // Python's Conversation(...) draws its id before its started_at; keep the
+    // same generator order so injected sequences line up with the oracle.
+    const conversationId = deps.newId();
+    const startedAt = deps.nowIso();
+    db.prepare(
+      `INSERT INTO conversations
+         (id, title, started_at, ended_at, interface, persona, journey, summary, tags, metadata)
+       VALUES (?, NULL, ?, ?, ?, NULL, NULL, NULL, NULL, NULL)`,
+    ).run(conversationId, startedAt, session.endedAt, session.interface);
+
+    const insertMessage = db.prepare(
+      `INSERT INTO messages (id, conversation_id, role, content, created_at, token_count, metadata)
+       VALUES (?, ?, ?, ?, ?, NULL, NULL)`,
+    );
+    for (const message of session.messages) {
+      insertMessage.run(
+        deps.newId(),
+        conversationId,
+        message.role,
+        message.content,
+        message.createdAt,
+      );
+    }
+
+    db.prepare(
+      `INSERT INTO runtime_sessions
+         (session_id, conversation_id, interface, mirror_active, persona, journey,
+          hook_injected, active, started_at, updated_at, closed_at, metadata)
+       VALUES (?, ?, ?, 0, NULL, NULL, 0, 0, ?, ?, ?, NULL)`,
+    ).run(sessionId, conversationId, session.interface, startedAt, startedAt, session.endedAt);
+
+    return conversationId;
+  });
+}

package/ts/src/conversation/transcriptBackfill.ts

@@ -0,0 +1,141 @@
+// Assistant-turn backfill from a Claude transcript (CV22.DS7.US10 slice E).
+//
+// Ports `backfill_assistant_messages` from
+// `src/memory/cli/conversation_logger.py` together with the two helpers it
+// borrows from `src/memory/cli/transcript_export.py` (`parse_jsonl`,
+// `_assistant_text`). `hook_session_end` calls it after ending the session --
+// and, when the payload carries no session id at all, INSTEAD of ending one:
+// that session-less route is the path US5's hook port deliberately left out.
+//
+// This is not an import: nothing is created or bound. It appends assistant
+// turns to conversations that overlap the transcript's time window and logged
+// no assistant message of their own, stamping each with `now` (Python's
+// `Message` default), not with the transcript timestamp. Python commits every
+// message as it goes and swallows nothing here; a malformed entry reached
+// mid-walk raises with the earlier appends already committed. The port keeps
+// that sequence so partial state matches, and leaves swallowing to the hook.
+
+import { readFileSync } from "node:fs";
+import type { LoggerDeps } from "#conversation/logger.ts";
+import type { WritableDatabase } from "#db/database.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Python `dict.get` on something that must be a dict; see `backfill.ts`. */
+function getOr(container: unknown, key: string, fallback: unknown): unknown {
+  if (!isRecord(container)) throw new TypeError(`expected an object with '${key}'`);
+  return key in container ? container[key] : fallback;
+}
+
+function getFrom(container: unknown, key: string): unknown {
+  return getOr(container, key, undefined);
+}
+
+/** Python `parse_jsonl`: blank lines skipped, unparseable lines skipped. */
+export function parseJsonl(path: string): unknown[] {
+  const entries: unknown[] = [];
+  for (const raw of readFileSync(path, "utf8").split(/\r?\n|\r/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // json.JSONDecodeError -> continue
+    }
+  }
+  return entries;
+}
+
+/**
+ * Python `_assistant_text`: the stripped, non-empty `text` blocks of an
+ * assistant message joined by a blank line. Iterating a string or a dict
+ * yields no dict items (so no text); a null or number cannot be iterated and
+ * raises, as does a text block whose `text` is not a string.
+ */
+export function assistantText(contentBlocks: unknown): string {
+  const iterable = Array.isArray(contentBlocks)
+    ? contentBlocks
+    : typeof contentBlocks === "string" || isRecord(contentBlocks)
+      ? []
+      : null;
+  if (iterable === null) throw new TypeError("assistant content is not iterable");
+  const parts: string[] = [];
+  for (const block of iterable) {
+    if (!isRecord(block) || block.type !== "text") continue;
+    const text = getOr(block, "text", "");
+    if (typeof text !== "string") throw new TypeError("text block is not a string");
+    const trimmed = text.trim();
+    if (trimmed) parts.push(trimmed);
+  }
+  return parts.join("\n\n");
+}
+
+/** Python `str` truthiness on the timestamp: absent, null, or empty is skipped. */
+function timestampOf(entry: unknown): string | null {
+  const value = getOr(entry, "timestamp", "");
+  return typeof value === "string" && value ? value : null;
+}
+
+/**
+ * Python `backfill_assistant_messages`. The transcript window is
+ * `[min(timestamp), max(timestamp)]` over entries that carry one; a
+ * conversation is in range when `started_at <= window end` and it either
+ * ended at or after the window start or is still open. Within an in-range
+ * conversation that has no assistant turn, every `assistant` entry whose
+ * timestamp falls inside `[started_at, ended_at or window end]` is appended.
+ */
+export function backfillAssistantMessages(
+  db: WritableDatabase,
+  transcriptPath: string,
+  deps: LoggerDeps,
+): void {
+  const entries = parseJsonl(transcriptPath);
+  if (entries.length === 0) return;
+
+  const timestamps = entries.map(timestampOf).filter((value): value is string => value !== null);
+  if (timestamps.length === 0) return;
+  // Python's min()/max() on str compare by code point; ISO timestamps are
+  // ASCII, so plain comparison is the same order.
+  let startTime = timestamps[0] as string;
+  let endTime = timestamps[0] as string;
+  for (const value of timestamps) {
+    if (value < startTime) startTime = value;
+    if (value > endTime) endTime = value;
+  }
+
+  const conversations = db
+    .prepare(
+      `SELECT id, started_at, ended_at FROM conversations
+        WHERE started_at <= ? AND (ended_at >= ? OR ended_at IS NULL)`,
+    )
+    .all(endTime, startTime) as { id: string; started_at: string; ended_at: string | null }[];
+
+  const hasAssistant = db.prepare(
+    "SELECT 1 FROM messages WHERE conversation_id = ? AND role = 'assistant' LIMIT 1",
+  );
+  const insert = db.prepare(
+    `INSERT INTO messages (id, conversation_id, role, content, created_at, token_count, metadata)
+     VALUES (?, ?, 'assistant', ?, ?, NULL, NULL)`,
+  );
+
+  for (const conversation of conversations) {
+    if (hasAssistant.get(conversation.id)) continue;
+    const conversationStart = conversation.started_at;
+    const conversationEnd = conversation.ended_at ?? endTime;
+
+    for (const entry of entries) {
+      const timestamp = timestampOf(entry);
+      if (!timestamp || !(conversationStart <= timestamp && timestamp <= conversationEnd)) continue;
+      if (getFrom(entry, "type") !== "assistant") continue;
+      const message = getOr(entry, "message", {});
+      const text = assistantText(getOr(message, "content", []));
+      if (text) {
+        // Python: Message(...) draws its id before its created_at.
+        const id = deps.newId();
+        insert.run(id, conversation.id, text, deps.nowIso());
+      }
+    }
+  }
+}