mirror-mind 0.0.1 → 0.33.0

package/ts/src/conversation/loggerCli.ts

@@ -0,0 +1,321 @@
+// `conversation-logger` CLI dispatch (CV22.DS7.US5 slice A; completed in
+// CV22.DS7.US10 slice F).
+//
+// Ports the argument handling and stdout contract of
+// `conversation_logger.main()`. The strangler's unit is
+// `command + args -> stdout`, so this module returns the output rather than
+// printing it: the front door writes it, and goldens grade it.
+//
+// Every subcommand of the family is dispatched here. The ones that cross the
+// LLM close tail (`switch`, `session-end`, `session-end-pi`, full
+// `session-start`, `session-maintenance`) get their tail from the runtime's
+// close hooks. (Until CV22.DS10.TS5 a reverted tail reported `{ handled:
+// false }` so the caller could fall back to Python; the revert left with the
+// fallback, and every result is now an answer.) `repair-journeys --apply`
+// needs the dated zip backup from the runtime (CV22.DS7.TS1) and refuses, like
+// Python, when it is not available.
+
+import { backfillCodexSession } from "#conversation/backfill.ts";
+import { diagnoseJourneyAssociations, renderJourneyFindings } from "#conversation/journeyRepair.ts";
+import {
+  discardCurrentConversation,
+  endSession,
+  handleSessionEndHook,
+  handleStopHook,
+  handleUserPromptHook,
+  isMuted,
+  logAssistantMessage,
+  logUserMessage,
+  setMute,
+  switchConversation,
+} from "#conversation/logger.ts";
+import type { LoggerRuntime } from "#conversation/loggerRuntime.ts";
+import {
+  sessionMaintenance,
+  sessionStart,
+  sessionStartFast,
+} from "#conversation/sessionComposites.ts";
+import type { WritableDatabase } from "#db/database.ts";
+
+export interface LoggerCliResult {
+  stdout: string[];
+  stderr: string[];
+  exitCode: number;
+}
+
+export interface LoggerCliContext {
+  stdin?: string;
+}
+
+/** Every subcommand `conversation_logger.main()` dispatches. */
+export const CONVERSATION_LOGGER_SUBCOMMANDS = [
+  "mute",
+  "unmute",
+  "status",
+  "log-user",
+  "log-assistant",
+  "user-prompt",
+  "stop",
+  "discard-current",
+  "switch",
+  "session-end-pi",
+  "session-end",
+  "session-start",
+  "session-maintenance",
+  "diagnose-journeys",
+  "repair-journeys",
+  "backfill-codex-session",
+] as const;
+
+/** The subcommands whose Python path runs `end_conversation`'s LLM close tail. */
+export const LLM_TAIL_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  "switch",
+  "session-end-pi",
+  "session-end",
+  "session-start",
+  "session-maintenance",
+]);
+
+/** Subcommands that read their JSON payload from stdin. */
+export const STDIN_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  "user-prompt",
+  "stop",
+  "session-end",
+]);
+
+function extractOption(
+  args: string[],
+  name: string,
+): { value: string | null; error: string | null } {
+  const index = args.indexOf(name);
+  if (index === -1) return { value: null, error: null };
+  if (index + 1 >= args.length) {
+    const noun = name === "--mirror-home" ? "a path" : name === "--limit" ? "a number" : "a value";
+    return { value: null, error: `Error: ${name} requires ${noun}` };
+  }
+  const value = args[index + 1] as string;
+  args.splice(index, 2);
+  return { value, error: null };
+}
+
+/** Python `"--interface" in args` followed by `args[idx + 1]` when present. */
+function interfaceOption(args: readonly string[], fallback: string): string {
+  const index = args.indexOf("--interface");
+  return index !== -1 && index + 1 < args.length ? (args[index + 1] as string) : fallback;
+}
+
+const ok = (stdout: string[]): LoggerCliResult => ({
+  stdout,
+  stderr: [],
+  exitCode: 0,
+});
+
+export async function runConversationLoggerCommand(
+  db: WritableDatabase,
+  argv: readonly string[],
+  runtime: LoggerRuntime,
+  context: LoggerCliContext = {},
+): Promise<LoggerCliResult> {
+  const args = [...argv];
+
+  // Python strips --mirror-home and --session-id before dispatch, failing with
+  // exit 1 when either is present without a value.
+  const mirrorHome = extractOption(args, "--mirror-home");
+  if (mirrorHome.error) {
+    return { stdout: [], stderr: [mirrorHome.error], exitCode: 1 };
+  }
+  const sessionOption = extractOption(args, "--session-id");
+  if (sessionOption.error) {
+    return { stdout: [], stderr: [sessionOption.error], exitCode: 1 };
+  }
+  if (args.length === 0) {
+    return { stdout: [], stderr: [], exitCode: 1 };
+  }
+
+  const command = args[0] as string;
+  if (!(CONVERSATION_LOGGER_SUBCOMMANDS as readonly string[]).includes(command)) {
+    // Python's main() silently exits 0 on an unknown subcommand.
+    return ok([]);
+  }
+
+  const home = mirrorHome.value ?? runtime.mirrorHome;
+  const deps = runtime.deps;
+
+  switch (command) {
+    case "mute":
+      setMute(true, home);
+      return ok(["Conversation logging MUTED."]);
+    case "unmute":
+      setMute(false, home);
+      return ok(["Conversation logging ACTIVE."]);
+    case "status":
+      return ok([isMuted(home) ? "MUTED" : "ACTIVE"]);
+
+    case "user-prompt":
+      // `--interface` is the runtime the hook detected (US8); without it the
+      // label is Python's hook default.
+      handleUserPromptHook(
+        db,
+        context.stdin ?? "",
+        { mirrorHome: home, interface: interfaceOption(args, "claude_code") },
+        deps,
+      );
+      // The hook is silent and always exits 0, whatever the outcome.
+      return ok([]);
+
+    case "stop": {
+      // The Stop hook's payload (US8): the turn's final answer, logged beside
+      // its prompt when one is waiting. Exit 0 whatever the outcome, and the
+      // outcome on stdout in one line: the hook entry runs this route
+      // in-process, reads the line, and forwards nothing -- a Stop hook that
+      // printed would keep the agent working on some runtimes -- while a
+      // person running the command from a shell sees what happened.
+      const outcome = handleStopHook(
+        db,
+        context.stdin ?? "",
+        { mirrorHome: home, interface: interfaceOption(args, "claude_code") },
+        deps,
+      );
+      switch (outcome.action) {
+        case "logged":
+          return ok([`reply logged (${outcome.pairedBy})`]);
+        case "skipped":
+          return ok([`reply skipped: ${outcome.reason}`]);
+        case "muted":
+          return ok(["reply not logged: muted"]);
+        default:
+          // The error text is the fault's, never the payload's.
+          return ok([`reply failed: ${outcome.error}`]);
+      }
+    }
+
+    case "session-end":
+      await handleSessionEndHook(
+        db,
+        context.stdin ?? "",
+        {
+          mirrorHome: home,
+          claudeProjectDir: runtime.claudeProjectDir,
+          homeDir: runtime.homeDir,
+        },
+        deps,
+        await runtime.closeHooks(),
+      );
+      return ok([]);
+
+    case "log-user":
+    case "log-assistant": {
+      const remaining = args.slice(1);
+      const interfaceName = extractOption(remaining, "--interface").value ?? "claude_code";
+      // Python silently does nothing with fewer than two positional arguments.
+      if (remaining.length >= 2) {
+        const [targetSession, content] = remaining as [string, string];
+        const write = command === "log-user" ? logUserMessage : logAssistantMessage;
+        write(db, targetSession, content, { interface: interfaceName }, deps);
+      }
+      return ok([]);
+    }
+
+    case "switch": {
+      const conversationId = await switchConversation(
+        db,
+        sessionOption.value,
+        { envSessionId: runtime.environmentSessionId },
+        deps,
+        await runtime.closeHooks(),
+      );
+      return ok([
+        conversationId ? `New conversation created: ${conversationId}` : "No active session found.",
+      ]);
+    }
+
+    case "session-start":
+      if (args.includes("--fast")) return ok([sessionStartFast(db, home, deps.nowIso)]);
+      return ok([await sessionStart(db, home, await runtime.maintenanceDeps())]);
+
+    case "session-maintenance":
+      return ok([await sessionMaintenance(db, await runtime.maintenanceDeps())]);
+
+    case "discard-current": {
+      const discarded = discardCurrentConversation(
+        db,
+        sessionOption.value,
+        { interface: interfaceOption(args, "pi") },
+        deps,
+      );
+      return ok([
+        discarded
+          ? `Discarded current conversation: ${discarded}`
+          : "No current conversation to discard.",
+      ]);
+    }
+
+    case "session-end-pi":
+      if (args.length >= 2) {
+        await endSession(
+          db,
+          args[1] as string,
+          { extract: false },
+          deps,
+          await runtime.closeHooks(),
+        );
+      }
+      return ok([]);
+
+    case "diagnose-journeys":
+    case "repair-journeys": {
+      const apply = command === "repair-journeys" && args.includes("--apply");
+      const limitOption = extractOption(args, "--limit");
+      if (limitOption.error) {
+        return { stdout: [], stderr: [limitOption.error], exitCode: 1 };
+      }
+      let limit: number | null = null;
+      if (limitOption.value !== null) {
+        // Python `int(value)` raises ValueError on anything but an integer.
+        if (!/^\s*[+-]?\d+\s*$/.test(limitOption.value)) {
+          return {
+            stdout: [],
+            stderr: [`ValueError: invalid literal for int() with base 10: '${limitOption.value}'`],
+            exitCode: 1,
+          };
+        }
+        limit = Number.parseInt(limitOption.value, 10);
+      }
+      // Python prints backup()'s progress from inside the repair, BEFORE the
+      // findings; the lines are collected here so the order survives.
+      const backupLines: string[] = [];
+      const backup = runtime.backup;
+      const findings = diagnoseJourneyAssociations(db, {
+        limit,
+        apply,
+        ...(apply && backup ? { backup: () => backup((line) => backupLines.push(line)) } : {}),
+      });
+      const lines = [
+        ...backupLines,
+        ...renderJourneyFindings(findings, apply).replace(/\n$/, "").split("\n"),
+      ];
+      if (command === "repair-journeys" && !apply) {
+        lines.push("Dry run only. Re-run with --apply to repair after reviewing candidates.");
+      }
+      return ok(lines);
+    }
+
+    case "backfill-codex-session": {
+      if (args.length < 2) return ok([]);
+      const path = args[1] as string;
+      const count = backfillCodexSession(
+        db,
+        { jsonlPath: path, interface: interfaceOption(args, "codex") },
+        deps,
+      );
+      return ok([
+        count
+          ? `Backfilled 1 Codex session from ${path}`
+          : `No new Codex session backfilled from ${path}`,
+      ]);
+    }
+
+    default:
+      return ok([]);
+  }
+}

package/ts/src/conversation/loggerRuntime.ts

@@ -0,0 +1,259 @@
+// The conversation-logger composition root (CV22.DS7.US10 slice F).
+//
+// Everything the `conversation-logger` subcommands need beyond the database
+// is assembled here, once per invocation, from an EXPLICIT environment: the
+// clock and id generator, the transcript/session resolution inputs, the Pi
+// sessions directory, the pre-write backup, and -- only for the subcommands
+// that cross the LLM close tail -- the replay providers and the maintenance
+// dependencies built on them.
+//
+// The providers are loaded lazily. `diagnose-journeys`, `backfill-codex-session`,
+// or `session-start --fast` must never fail because a replay fixture is not
+// configured, and `switch` or `session-end` must fail loudly (and fall back
+// to Python at the routing layer) when it is not: "unconfigured installs keep
+// Python fallback" is the plan's live-cutover boundary, and this is where it
+// is enforced on the TypeScript side.
+//
+// Nothing here reads `process.env` or `os.homedir()`; the front door passes
+// them in, which is what keeps every test of this module hermetic.
+
+import { backfillPiSessions, homeBornAt, resolvePiSessionsDir } from "#conversation/backfill.ts";
+import { createCloseHooks, maybeGenerateTitle } from "#conversation/closeTail.ts";
+import { runConversationExtraction } from "#conversation/extraction.ts";
+import { runExtractionWithAccounting } from "#conversation/extractionRun.ts";
+import { type CloseHooks, endConversation, type LoggerDeps } from "#conversation/logger.ts";
+import type { MaintenanceDeps } from "#conversation/sessionComposites.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { logLlmCall } from "#observability/llmCalls.ts";
+import {
+  resolveExtractionMaxAttempts,
+  resolveExtractionModel,
+  resolveMaintenanceMaxExtractions,
+  resolveSummarizeEnabled,
+  resolveTwoPassEnabled,
+} from "#providers/config.ts";
+import { computeCost } from "#providers/cost.ts";
+import type { EmbeddingProvider } from "#providers/embedding.ts";
+import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import type { LlmProvider, LlmResponse } from "#providers/llm.ts";
+import {
+  CONVERSATION_TAIL_TRANSPORT,
+  type ProviderTransportMode,
+  resolveProviderTransport,
+} from "#providers/transport.ts";
+
+/** The environment names the logger runtime reads. */
+export type LoggerRuntimeEnv = {
+  MIRROR_SESSION_ID?: string;
+  CLAUDE_PROJECT_DIR?: string;
+  PI_SESSIONS_DIR?: string;
+  MIRROR_TS_CONVERSATION_LLM_REPLAY?: string;
+  MIRROR_TS_CONVERSATION_EMBEDDING_REPLAY?: string;
+  /** Read by the live providers when the close tail runs against a real model. */
+  OPENROUTER_API_KEY?: string;
+  MEMORY_LLM_TIMEOUT_EXTRACTION?: string;
+  MEMORY_LLM_MAX_RETRIES?: string;
+  MEMORY_EMBEDDING_MODEL?: string;
+  MEMORY_SUMMARIZE?: string;
+  MEMORY_TWO_PASS?: string;
+  MEMORY_MAINTENANCE_MAX_EXTRACTIONS?: string;
+  MEMORY_EXTRACTION_MAX_ATTEMPTS?: string;
+  MEMORY_EXTRACTION_MODEL?: string;
+};
+
+export interface LoggerRuntimeOptions {
+  db: WritableDatabase;
+  mirrorHome: string;
+  homeDir: string;
+  env: LoggerRuntimeEnv;
+  deps: LoggerDeps;
+  /**
+   * Live provider factory, injectable for tests (CV22.DS8.US2).
+   *
+   * `loadLlm`/`loadEmbeddings` below are REPLAY-path loaders and are not
+   * consulted in live mode, so without this seam no test could exercise the
+   * close tail against a failing or instrumented live provider -- which is the
+   * behavior this story exists to change.
+   */
+  liveProviders?: (env: LoggerRuntimeEnv) => {
+    llm: LlmProvider;
+    embeddings: EmbeddingProvider;
+  };
+  /** Provider loaders, injectable for tests; default to the replay fixtures. */
+  loadLlm?: (path: string) => Promise<LlmProvider>;
+  loadEmbeddings?: (path: string) => Promise<EmbeddingProvider>;
+  /** Monotonic seconds for the maintenance report; defaults to `performance.now()`. */
+  monotonic?: () => number;
+  /**
+   * The dated zip backup `repair-journeys --apply` gates on (CV22.DS7.TS1).
+   * Prints its progress through `stdout` and returns the archive path, or
+   * null on failure. Absent (tests, unwired callers) means the repair refuses,
+   * exactly as Python refuses when `backup()` returns None.
+   */
+  backup?: (stdout: (line: string) => void) => string | null;
+}
+
+export interface LoggerRuntime {
+  readonly deps: LoggerDeps;
+  readonly mirrorHome: string;
+  readonly homeDir: string;
+  readonly claudeProjectDir: string | null;
+  readonly environmentSessionId: string | null;
+  readonly piSessionsDir: string;
+  /** Which transport answers the close tail here: replay, incomplete replay, or live. */
+  readonly transportMode: ProviderTransportMode;
+  /** The close hooks (extraction + finalization) behind the replay transport. */
+  closeHooks(): Promise<CloseHooks>;
+  /** The full maintenance wiring, including the real Pi backfill. */
+  maintenanceDeps(): Promise<MaintenanceDeps>;
+  /** The dated zip backup for the mutating journey repair; see `LoggerRuntimeOptions.backup`. */
+  readonly backup: ((stdout: (line: string) => void) => string | null) | null;
+}
+
+/**
+ * Adapt the close tail's PAIR-shaped live seam to the factory's per-kind
+ * overrides, memoized so one invocation builds one pair.
+ *
+ * The pair shape is load-bearing for tests: an atomicity test that fails the
+ * embedding on the second memory needs the same provider objects the close
+ * tail will call. Absent, the factory's own live defaults apply -- the default
+ * is not duplicated here.
+ */
+function liveTailOverrides(
+  env: LoggerRuntimeEnv,
+  liveProviders: LoggerRuntimeOptions["liveProviders"],
+): { liveLlm?: () => LlmProvider; liveEmbedding?: () => EmbeddingProvider } {
+  if (!liveProviders) return {};
+  let pair: { llm: LlmProvider; embeddings: EmbeddingProvider } | null = null;
+  const build = () => {
+    pair ??= liveProviders(env);
+    return pair;
+  };
+  return { liveLlm: () => build().llm, liveEmbedding: () => build().embeddings };
+}
+
+export function createLoggerRuntime(options: LoggerRuntimeOptions): LoggerRuntime {
+  const { db, env, deps } = options;
+  const piSessionsDir = resolvePiSessionsDir(null, env, options.homeDir);
+
+  // One precedence, shared with the router so the two cannot disagree about
+  // which transport is live: replay -> incomplete -> live. The pair rule that
+  // used to live here is now in the spec itself (CR077), so the router and
+  // this runtime refuse a half-configured fixture with the same reason.
+  const transport = resolveProviderTransport(env, CONVERSATION_TAIL_TRANSPORT);
+
+  let providers: Promise<{ llm: LlmProvider; embeddings: EmbeddingProvider }> | null = null;
+  const loadProviders = () => {
+    providers ??= resolveFamilyProviders(env, CONVERSATION_TAIL_TRANSPORT, {
+      loadReplayLlm: options.loadLlm,
+      loadReplayEmbedding: options.loadEmbeddings,
+      ...liveTailOverrides(env, options.liveProviders),
+    }).then((family) => {
+      // The factory declares both kinds for this family, so both are present
+      // by construction.
+      const llm = family.llm;
+      const embeddings = family.embedding;
+      if (!llm || !embeddings) {
+        throw new Error("the conversation close tail requires an LLM and an embedding provider");
+      }
+      return { llm, embeddings };
+    });
+    return providers;
+  };
+
+  // Python's `_make_logger(role, conversation_id)`: one ledger row per
+  // successful close-tail call, priced through the cost authority exactly as
+  // `build_llm_logger` prices it (CV22.DS8.US2).
+  //
+  // This is the sibling of `extraction.ts`'s llmLedger and was missed when
+  // that one was fixed: the close-tail METADATA roles (title, tags, summary)
+  // log through here, so they carried token counts and a null cost while the
+  // extraction roles were priced. Found by the live smoke on real data, not by
+  // a test -- under replay no usage comes back, so both look identical.
+  const ledger = (role: string, response: LlmResponse, conversationId: string, prompt: string) => {
+    const model = response.model ?? resolveExtractionModel({ env });
+    logLlmCall(
+      db,
+      {
+        role,
+        model,
+        prompt,
+        response: response.content,
+        promptTokens: response.promptTokens ?? null,
+        completionTokens: response.completionTokens ?? null,
+        latencyMs: response.latencyMs ?? null,
+        costUsd: computeCost(
+          model,
+          response.promptTokens ?? null,
+          response.completionTokens ?? null,
+        ),
+        conversationId,
+      },
+      { now: deps.nowIso },
+    );
+  };
+
+  const maxAttempts = resolveExtractionMaxAttempts({ env });
+  const runExtraction = async (database: WritableDatabase, conversationId: string) => {
+    const { llm, embeddings } = await loadProviders();
+    await runExtractionWithAccounting(
+      database,
+      conversationId,
+      (innerDb, id) =>
+        runConversationExtraction(innerDb, id, {
+          llm,
+          embeddings,
+          now: deps.nowIso,
+          id: deps.newId,
+          summarize: resolveSummarizeEnabled({ env }),
+          twoPass: resolveTwoPassEnabled({ env }),
+          ledger: true,
+        }),
+      maxAttempts,
+    );
+  };
+
+  const closeHooks = async (): Promise<CloseHooks> => {
+    const { llm } = await loadProviders();
+    return createCloseHooks({ llm, onLlmCall: ledger, now: deps.nowIso, runExtraction });
+  };
+
+  return {
+    deps,
+    mirrorHome: options.mirrorHome,
+    homeDir: options.homeDir,
+    claudeProjectDir: env.CLAUDE_PROJECT_DIR || null,
+    environmentSessionId: env.MIRROR_SESSION_ID?.trim() || null,
+    piSessionsDir,
+    transportMode: transport.mode,
+    backup: options.backup ?? null,
+    closeHooks,
+    async maintenanceDeps(): Promise<MaintenanceDeps> {
+      const { llm } = await loadProviders();
+      const hooks = createCloseHooks({ llm, onLlmCall: ledger, now: deps.nowIso, runExtraction });
+      return {
+        closeConversation: (database, conversationId) =>
+          endConversation(database, conversationId, { extract: true }, deps, hooks),
+        retitleConversation: (database, conversationId) =>
+          maybeGenerateTitle(database, conversationId, {
+            llm,
+            onLlmCall: ledger,
+            now: deps.nowIso,
+            source: "startup_maintenance",
+          }),
+        runExtraction,
+        // CR121: only the sessions newer than this home; its birth is read from
+        // the ledger once per maintenance run, and an unknown birth is an error.
+        backfillPiSessions: (database) =>
+          backfillPiSessions(
+            database,
+            { sessionsDir: piSessionsDir, notBefore: homeBornAt(database) },
+            deps,
+          ),
+        extractionLimit: resolveMaintenanceMaxExtractions({ env }),
+        monotonic: options.monotonic,
+        now: deps.nowIso,
+      };
+    },
+  };
+}