mirror-mind 0.0.1 → 0.33.0

package/ts/src/mirror/runtimeSession.ts

@@ -0,0 +1,205 @@
+import type { Database, WritableDatabase } from "#db/database.ts";
+
+export const GLOBAL_STICKY_DEFAULTS_SESSION_ID = "__global_sticky_defaults__";
+export const GLOBAL_OPERATING_MODE_SESSION_ID = "__global_operating_mode__";
+
+export interface RuntimeSessionRow {
+  sessionId: string;
+  conversationId: string | null;
+  interface: string | null;
+  mirrorActive: boolean;
+  persona: string | null;
+  journey: string | null;
+  hookInjected: boolean;
+  active: boolean;
+  startedAt: string;
+  updatedAt: string;
+  closedAt: string | null;
+  metadata: string | null;
+}
+
+export interface RuntimeSessionPatch {
+  conversationId?: string | null;
+  interface?: string | null;
+  mirrorActive?: boolean;
+  persona?: string | null;
+  journey?: string | null;
+  hookInjected?: boolean;
+  active?: boolean;
+  closedAt?: string | null;
+  metadata?: string | null;
+}
+
+export function getRuntimeSession(db: Database, sessionId: string): RuntimeSessionRow | null {
+  const row = db.prepare("SELECT * FROM runtime_sessions WHERE session_id = ?").get(sessionId);
+  if (!row) return null;
+  return {
+    sessionId: String(row.session_id),
+    conversationId: nullableString(row.conversation_id),
+    interface: nullableString(row.interface),
+    mirrorActive: Boolean(row.mirror_active),
+    persona: nullableString(row.persona),
+    journey: nullableString(row.journey),
+    hookInjected: Boolean(row.hook_injected),
+    active: Boolean(row.active),
+    startedAt: String(row.started_at),
+    updatedAt: String(row.updated_at),
+    closedAt: nullableString(row.closed_at),
+    metadata: nullableString(row.metadata),
+  };
+}
+
+export function upsertRuntimeSession(
+  db: WritableDatabase,
+  sessionId: string,
+  patch: RuntimeSessionPatch,
+  nowIso: string,
+): RuntimeSessionRow {
+  const existing = getRuntimeSession(db, sessionId);
+  const value = <K extends keyof RuntimeSessionPatch>(
+    key: K,
+    fallback: RuntimeSessionRow[keyof RuntimeSessionRow],
+  ) => (patch[key] === undefined ? fallback : patch[key]);
+  const row: RuntimeSessionRow = {
+    sessionId,
+    conversationId: value("conversationId", existing?.conversationId ?? null) as string | null,
+    interface: value("interface", existing?.interface ?? null) as string | null,
+    mirrorActive: value("mirrorActive", existing?.mirrorActive ?? false) as boolean,
+    persona: value("persona", existing?.persona ?? null) as string | null,
+    journey: value("journey", existing?.journey ?? null) as string | null,
+    hookInjected: value("hookInjected", existing?.hookInjected ?? false) as boolean,
+    active: value("active", existing?.active ?? true) as boolean,
+    startedAt: existing?.startedAt ?? nowIso,
+    updatedAt: nowIso,
+    closedAt: value("closedAt", existing?.closedAt ?? null) as string | null,
+    metadata: value("metadata", existing?.metadata ?? null) as string | null,
+  };
+  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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(session_id) DO UPDATE SET
+       conversation_id = excluded.conversation_id,
+       interface = excluded.interface,
+       mirror_active = excluded.mirror_active,
+       persona = excluded.persona,
+       journey = excluded.journey,
+       hook_injected = excluded.hook_injected,
+       active = excluded.active,
+       updated_at = excluded.updated_at,
+       closed_at = excluded.closed_at,
+       metadata = excluded.metadata`,
+  ).run(
+    row.sessionId,
+    row.conversationId,
+    row.interface,
+    Number(row.mirrorActive),
+    row.persona,
+    row.journey,
+    Number(row.hookInjected),
+    Number(row.active),
+    row.startedAt,
+    row.updatedAt,
+    row.closedAt,
+    row.metadata,
+  );
+  return row;
+}
+
+/**
+ * Python `compare_and_swap_runtime_session_metadata` (CV22.DS7.US8 plateau 2).
+ *
+ * Replace `metadata` only while it still equals the caller's observed value, and
+ * report whether the swap happened. The match is STRING EQUALITY on the stored
+ * metadata, which is what makes the delivery cursor's serialization a contract
+ * rather than a detail: a cursor written with different bytes for the same state
+ * cannot be swapped, so a cursor the Python engine wrote -- every database from
+ * before CV22.DS10.TS5 carries them -- would fail its first TypeScript write.
+ *
+ * The WHERE clause also requires `active = 1`, so a cleared row can never be
+ * swapped back into place.
+ */
+export function compareAndSwapRuntimeSessionMetadata(
+  db: WritableDatabase,
+  sessionId: string,
+  options: { expectedMetadata: string; metadata: string },
+  nowIso: string,
+): boolean {
+  const result = db
+    .prepare(
+      `UPDATE runtime_sessions
+          SET metadata = ?, updated_at = ?
+        WHERE session_id = ? AND active = 1 AND metadata = ?`,
+    )
+    .run(options.metadata, nowIso, sessionId, options.expectedMetadata);
+  return Number(result.changes) === 1;
+}
+
+/**
+ * The session a caller was TOLD about: `--session-id`, else `MIRROR_SESSION_ID`.
+ * `null` means nobody named one. It never guesses, so it is the only resolver a
+ * caller may bind a journey or write project state on (CR008).
+ */
+export function resolveNamedRuntimeSessionId(
+  explicitSessionId: string | null,
+  environmentSessionId: string | null = null,
+): string | null {
+  if (explicitSessionId?.trim()) return explicitSessionId;
+  if (environmentSessionId?.trim()) return environmentSessionId.trim();
+  return null;
+}
+
+/**
+ * A named session if there is one, else a GUESS: the most recently updated active
+ * row that is not a global pseudo-session.
+ *
+ * The guess is usually the active window, because the Pi extension logs each
+ * prompt under its own session id before any tool runs. It is wrong under
+ * interleaving (another window's prompt in between), and delivery-cursor rows
+ * qualify, so a lifecycle write can make a cursor "the session". Builder binding
+ * stopped using it in CR008; the callers that still do are CR100's.
+ */
+export function resolveRuntimeSessionId(
+  db: Database,
+  explicitSessionId: string | null,
+  environmentSessionId: string | null = null,
+): string | null {
+  return (
+    resolveNamedRuntimeSessionId(explicitSessionId, environmentSessionId) ??
+    guessRuntimeSessionId(db)
+  );
+}
+
+function guessRuntimeSessionId(db: Database): string | null {
+  const row = db
+    .prepare(
+      `SELECT session_id FROM runtime_sessions
+       WHERE active = 1
+         AND session_id NOT IN (?, ?)
+         AND interface IS NOT NULL
+         AND interface != 'global_defaults'
+       ORDER BY updated_at DESC
+       LIMIT 1`,
+    )
+    .get(GLOBAL_OPERATING_MODE_SESSION_ID, GLOBAL_STICKY_DEFAULTS_SESSION_ID);
+  return row ? String(row.session_id) : null;
+}
+
+export function decodeMetadata(raw: string | null): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    const value: unknown = JSON.parse(raw);
+    return isRecord(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function nullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/ts/src/mode/operatingMode.ts

@@ -0,0 +1,148 @@
+import type { Database, WritableDatabase } from "#db/database.ts";
+import {
+  decodeMetadata,
+  GLOBAL_OPERATING_MODE_SESSION_ID,
+  getRuntimeSession,
+  upsertRuntimeSession,
+} from "#mirror/runtimeSession.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+
+export const OPERATING_MODE_METADATA_KEY = "operating_mode";
+
+// `runtime_sessions.metadata` is written by BOTH cores for as long as any
+// command that touches it is still on Python -- Soul (DS7.US6) shares the very
+// same row and object. Python writes it with `json.dumps(..., ensure_ascii=
+// False)`, whose separators are `", "` and `": "`; `JSON.stringify` writes
+// neither and escapes nothing, so the two cores stored different bytes for
+// identical state until DS7.US6 corrected it. Nothing failed, because both the
+// mirror-state golden and the write-parity harness compare metadata by VALUE --
+// which is exactly why the divergence survived. The bytes are pinned directly
+// by `operating-mode-metadata.golden.json`.
+
+/** Port of `MODE_ICONS`: the glyph each lens is announced with. */
+export const MODE_ICONS: Readonly<Record<string, string>> = {
+  "Mirror Mode": "◌",
+  "Builder Mode": "■",
+  "Explorer Mode": "△",
+  "Soul Mode": "☾",
+};
+
+/** Port of `OperatingModeState.label`: the icon, then the mode, or just the mode. */
+export function modeLabel(state: OperatingModeState): string {
+  const icon = MODE_ICONS[state.mode];
+  return icon ? `${icon} ${state.mode}` : state.mode;
+}
+
+export interface OperatingModeState {
+  mode: string;
+  journey: string | null;
+}
+
+export function activateOperatingMode(
+  db: WritableDatabase,
+  input: { mode: string; journey?: string | null; sessionId?: string | null },
+  nowIso: string,
+): OperatingModeState {
+  const mode = input.mode.trim();
+  if (!mode) throw new Error("mode must not be empty");
+  const journey = input.journey?.trim() || null;
+  const state = { mode, journey };
+  const payload = { active_mode: mode, active_journey: journey };
+  if (input.sessionId) {
+    const session = getRuntimeSession(db, input.sessionId);
+    const metadata = decodeMetadata(session?.metadata ?? null);
+    metadata[OPERATING_MODE_METADATA_KEY] = payload;
+    upsertRuntimeSession(
+      db,
+      input.sessionId,
+      { metadata: pythonJsonDumps(metadata), active: true },
+      nowIso,
+    );
+  } else {
+    upsertRuntimeSession(
+      db,
+      GLOBAL_OPERATING_MODE_SESSION_ID,
+      { metadata: pythonJsonDumps(payload), active: true },
+      nowIso,
+    );
+  }
+  return state;
+}
+
+export function deactivateOperatingMode(
+  db: WritableDatabase,
+  sessionId: string | null,
+  nowIso: string,
+): void {
+  if (!sessionId) {
+    upsertRuntimeSession(
+      db,
+      GLOBAL_OPERATING_MODE_SESSION_ID,
+      { metadata: null, active: false },
+      nowIso,
+    );
+    return;
+  }
+  const session = getRuntimeSession(db, sessionId);
+  if (!session) return;
+  const metadata = decodeMetadata(session.metadata);
+  delete metadata[OPERATING_MODE_METADATA_KEY];
+  upsertRuntimeSession(
+    db,
+    sessionId,
+    { metadata: Object.keys(metadata).length > 0 ? pythonJsonDumps(metadata) : null },
+    nowIso,
+  );
+}
+
+/**
+ * The mode stamped on ONE session row, with no fallback (CR008).
+ *
+ * A caller that binds on the answer must read this, not `getActiveOperatingMode`:
+ * that one falls back to the global row, which whichever window loaded last
+ * wrote.
+ */
+export function getSessionOperatingMode(
+  db: Database,
+  sessionId: string,
+): OperatingModeState | null {
+  const session = getRuntimeSession(db, sessionId);
+  return stateFromPayload(decodeMetadata(session?.metadata ?? null)[OPERATING_MODE_METADATA_KEY]);
+}
+
+/** The session's own mode, else the global row: what the status line displays. */
+export function getActiveOperatingMode(
+  db: Database,
+  sessionId: string | null,
+): OperatingModeState | null {
+  if (sessionId) {
+    const state = getSessionOperatingMode(db, sessionId);
+    if (state) return state;
+  }
+  const global = getRuntimeSession(db, GLOBAL_OPERATING_MODE_SESSION_ID);
+  if (!global?.active) return null;
+  return stateFromPayload(decodeMetadata(global.metadata));
+}
+
+function stateFromPayload(payload: unknown): OperatingModeState | null {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
+  const record = payload as Record<string, unknown>;
+  const mode = typeof record.active_mode === "string" ? record.active_mode.trim() : "";
+  if (!mode) return null;
+  const journey =
+    typeof record.active_journey === "string" && record.active_journey.trim()
+      ? record.active_journey.trim()
+      : null;
+  return { mode, journey };
+}
+
+export function renderModeActivation(state: OperatingModeState): string {
+  return state.journey
+    ? `Activated ${state.mode} for ${state.journey}\n`
+    : `Activated ${state.mode}\n`;
+}
+
+export function renderModeStatus(state: OperatingModeState | null): string {
+  if (!state) return "Mirror Mode\n";
+  return state.journey ? `${state.mode} · ${state.journey}\n` : `${state.mode}\n`;
+}

package/ts/src/observability/callOutcome.ts

@@ -0,0 +1,115 @@
+/**
+ * What actually happened on one provider-backed call (CV22.DS8.US3).
+ *
+ * Three leaves in this story swallow every failure, faithfully: Python's
+ * `propose_consolidation` returns `None`, `propose_shadow_observations`
+ * returns `[]`, and `reception` returns an empty result — for a transport
+ * error, for output the parser rejects, and for an honest "nothing to say"
+ * alike. Reproducing that is correct parity, and it means a live run can
+ * report "no proposals found", cost real money, and look identical to a
+ * healthy run that genuinely found nothing.
+ *
+ * So the swallow stays, and the DIAGNOSIS travels beside it: one outcome per
+ * call, category only, into the front-door log. That is what lets the live
+ * smoke read outcomes instead of counting rows — a zero-proposal run that
+ * passed a count-based check is exactly the shape of the US2 false start
+ * ("zero live calls, clean report") arriving one story later
+ * (CV22.DS8.US3 plan review, ai-engineer).
+ *
+ * One taxonomy for every surface rather than a per-surface vocabulary. The
+ * plan sketched `proposed|no_action|…` for cultivation and `ok|empty|…` for
+ * reception; two vocabularies is two maps to keep in step, which is the
+ * `LLM_ROLES` shape. The log line already names the surface, so the outcome
+ * only has to name the SHAPE of what happened.
+ */
+
+import { ProviderConfigError } from "#providers/config.ts";
+import { LlmTransportError } from "#providers/openrouter.ts";
+
+export type ProviderCallOutcome =
+  /** The model answered, the parser accepted it, and it carried a result. */
+  | "answered"
+  /** The model answered and the parser accepted it, but there was no result. */
+  | "empty"
+  /** A response arrived that the parser could not use. A PROMPT-layer signal. */
+  | "parse_failed"
+  /** No usable response arrived. A TRANSPORT-layer signal; `kind` narrows it. */
+  | "transport_failed";
+
+export interface ProviderCallReport {
+  outcome: ProviderCallOutcome;
+  /** The AI-18 taxonomy class, only for `transport_failed`. Never a message. */
+  kind?: string;
+}
+
+export type OnProviderCallOutcome = (report: ProviderCallReport) => void;
+
+/**
+ * Reduce a provider failure to its CLASS. Only the class travels: provider
+ * messages can echo request content, and the front-door log forbids payloads.
+ */
+export function classifyProviderError(error: unknown): string {
+  if (error instanceof ProviderConfigError) return "config";
+  if (error instanceof LlmTransportError) return error.kind;
+  return "unknown";
+}
+
+/** `outcome=… kind=…`, the content-free form the front-door log carries. */
+export function formatCallOutcome(surface: string, report: ProviderCallReport): string {
+  const kind = report.kind ? ` kind=${report.kind}` : "";
+  return `${surface} outcome=${report.outcome}${kind}`;
+}
+
+/**
+ * Collect per-call reports and render one summary line per invocation.
+ *
+ * `calls=N` is the fan-out number: `descriptor generate` without
+ * `--layer/--key` makes one call per persona AND per journey, and
+ * `consolidate scan` one per cluster. Neither is bounded by anything but an
+ * argument, so a runaway should be visible after the fact without reading the
+ * ledger (CV22.DS8.US3 plan review, security).
+ */
+export class CallOutcomeTally {
+  private readonly reports: ProviderCallReport[] = [];
+
+  record(report: ProviderCallReport): void {
+    this.reports.push(report);
+  }
+
+  get calls(): number {
+    return this.reports.length;
+  }
+
+  /** `calls=3 answered=2 parse_failed=1`, in a stable outcome order. */
+  summary(): string {
+    const order: ProviderCallOutcome[] = ["answered", "empty", "parse_failed", "transport_failed"];
+    const counts = order
+      .map(
+        (outcome) => [outcome, this.reports.filter((r) => r.outcome === outcome).length] as const,
+      )
+      .filter(([, count]) => count > 0)
+      .map(([outcome, count]) => `${outcome}=${count}`);
+    return [`calls=${this.calls}`, ...counts].join(" ");
+  }
+
+  /**
+   * `timeout=2 rate_limit=1` -- the transport-failure classes behind a
+   * `transport_failed=N`, or `""` when there were none. Kept apart from
+   * `summary()` so that line's pinned shape stays stable; the first live
+   * `consolidate scan` (CV22.DS8.TS2) reported `transport_failed=2` and
+   * nothing else, and the kind is the one field that separates a slow
+   * provider from a rate limit from a bad body.
+   */
+  failureKinds(): string {
+    const counts = new Map<string, number>();
+    for (const report of this.reports) {
+      if (report.outcome !== "transport_failed") continue;
+      const kind = report.kind ?? "unknown";
+      counts.set(kind, (counts.get(kind) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([kind, count]) => `${kind}=${count}`)
+      .join(" ");
+  }
+}