mirror-mind 0.0.1 → 0.33.0

package/ts/src/mcp/tools/deterministic.ts

@@ -0,0 +1,137 @@
+// The five MCP tools that never cross a provider (CV22.DS9.US2 plateau 3).
+//
+// `list_journeys`, `journey_status`, `list_conversations`, `recall_conversation`,
+// and `detect_persona` are plain database reads. Each returns the exact text its
+// Python handler returns -- `json.dumps(value, ensure_ascii=False, indent=2,
+// default=str)` -- which is what the model on the other end reads.
+//
+// The two provider-crossing tools (`search_memories` with a query, and
+// `mirror_context`) live in their own module.
+
+import { listRecentConversationSummaries } from "#conversation/listing.ts";
+import { findConversationByIdPrefix, pythonTailSliceStart } from "#conversation/recall.ts";
+import type { Database, Row } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+import { detectPersona, type PersonaRoutingRow } from "#persona/detectPersona.ts";
+import { pyFloat, pythonJson } from "../payload.ts";
+import { journeyStatus, listActiveJourneyDtos, recallMessages } from "../readModels.ts";
+
+/** Python's `_json`: pretty, unescaped, two-space indent. */
+export function toolJson(value: unknown): string {
+  return pythonJson(value, { indent: 2 });
+}
+
+/** Read an argument that Python would have taken straight off the dict. */
+function argument(args: unknown, key: string): unknown {
+  if (args === null || typeof args !== "object" || Array.isArray(args)) return undefined;
+  return (args as Record<string, unknown>)[key];
+}
+
+/**
+ * Python's `int(args.get("limit", fallback))`.
+ *
+ * `int("5")` and `int(5.9)` both succeed in Python, so a string or float limit
+ * is coerced rather than rejected. Argument VALIDATION is CV22.DS9.TS1's; this
+ * reproduces the oracle, including the limits US1's threat model recorded as
+ * unbounded.
+ */
+function pythonInt(value: unknown, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === "number") return Math.trunc(value);
+  if (typeof value === "string") {
+    const parsed = Number(value.trim());
+    if (Number.isFinite(parsed)) return Math.trunc(parsed);
+    throw new Error(`invalid literal for int() with base 10: '${value}'`);
+  }
+  if (typeof value === "boolean") return value ? 1 : 0;
+  throw new Error(`int() argument must be a string or a number, not '${typeof value}'`);
+}
+
+export function listJourneysTool(db: Database, _args: unknown): string {
+  return toolJson(listActiveJourneyDtos(db));
+}
+
+export function journeyStatusTool(db: Database, args: unknown): string {
+  const slug = argument(args, "slug");
+  return toolJson(journeyStatus(db, typeof slug === "string" ? slug : null));
+}
+
+export function listConversationsTool(db: Database, args: unknown): string {
+  const summaries = listRecentConversationSummaries(db, {
+    limit: pythonInt(argument(args, "limit"), 20),
+    journey: (argument(args, "journey") as string | undefined) ?? undefined,
+    persona: (argument(args, "persona") as string | undefined) ?? undefined,
+  });
+  return toolJson(
+    summaries.map((summary) => ({
+      id: summary.id,
+      title: summary.title,
+      started_at: summary.started_at,
+      persona: summary.persona,
+      journey: summary.journey,
+      message_count: summary.message_count,
+    })),
+  );
+}
+
+export function recallConversationTool(db: Database, args: unknown): string {
+  const conversationId = argument(args, "conversation_id");
+  if (!conversationId) throw new Error("'conversation_id' is required");
+  const conversation = findConversationByIdPrefix(db, String(conversationId));
+  if (conversation === null) throw new Error(`no conversation matching '${conversationId}'`);
+
+  const limit = pythonInt(argument(args, "limit"), 50);
+  const messages = recallMessages(db, conversation.id);
+  // `messages[-limit:]` -- and `-0 == 0` in Python, so limit=0 returns the WHOLE
+  // transcript rather than none. Recorded in the golden and owned by the DS9
+  // threat model; TS1 caps it, and this stays faithful until it does.
+  const tail = messages.slice(pythonTailSliceStart(messages.length, limit));
+
+  return toolJson({
+    conversation_id: conversation.id,
+    messages: tail.map((message) => ({
+      role: message.role,
+      content: message.content,
+      created_at: message.created_at,
+    })),
+  });
+}
+
+/** Python's `_persona_metadata(identity).get("routing_keywords") or []`. */
+function routingKeywords(metadata: unknown): string[] {
+  if (typeof metadata !== "string" || metadata === "") return [];
+  try {
+    const parsed = JSON.parse(metadata) as Record<string, unknown>;
+    if (!Array.isArray(parsed.routing_keywords)) return [];
+    return parsed.routing_keywords.filter((item): item is string => typeof item === "string");
+  } catch {
+    return [];
+  }
+}
+
+function personaRoutingRows(db: Database): PersonaRoutingRow[] {
+  return db
+    .prepare("SELECT key, metadata FROM identity WHERE layer = 'persona' ORDER BY key")
+    .all()
+    .map((row: Row) => ({
+      key: requireString(row, "key"),
+      routing_keywords: routingKeywords(optionalString(row, "metadata")),
+    }));
+}
+
+export function detectPersonaTool(db: Database, args: unknown): string {
+  const query = argument(args, "query");
+  if (!query) throw new Error("'query' is required");
+  const matches = detectPersona(String(query), personaRoutingRows(db));
+  return toolJson(
+    matches.map((match) => ({
+      persona: match.key,
+      // Python types this as float, and hit counts are routinely whole -- 2.0,
+      // not 2. JavaScript cannot tell the two apart, so the mapper says so.
+      score: pyFloat(match.score),
+      // Python appends the literal "keyword" as the third tuple element; the TS
+      // port carries it as `matchType`, and the tool renders it as `descriptor`.
+      descriptor: match.matchType,
+    })),
+  );
+}

package/ts/src/mcp/tools/providerCrossing.ts

@@ -0,0 +1,187 @@
+// The two MCP tools that can reach a provider (CV22.DS9.US2 plateau 4).
+//
+// `search_memories` with a `query` embeds it; `mirror_context` with a `query`
+// reaches attachment search and every installed extension context provider.
+// Both are the paid, fan-out paths the DS9 threat model names -- and, per the
+// AI-19 rider, the ones DS9.TS1 will put a wallet guard in front of.
+//
+// Everything else here is a deterministic read: `search_memories` without a
+// query is a filter over `memories`, and `mirror_context` without one assembles
+// identity layers from the database.
+
+import type { Database } from "#db/database.ts";
+import { collectExtensionContext } from "#extensions/contextRuntime.ts";
+import { loadMirrorContext } from "#mirror/context.ts";
+import type { EmbeddingAttemptInfo, EmbeddingProvider } from "#providers/embedding.ts";
+import { searchMemories } from "#search/memorySearch.ts";
+import { pyFloat, pythonJson } from "../payload.ts";
+import { type MemoryDto, memoriesByFilter, memoriesByIds } from "../readModels.ts";
+
+/** What the tools need from the process to reach providers and extensions. */
+export interface ToolRuntime {
+  embeddingProvider: EmbeddingProvider;
+  /**
+   * Where an agent-initiated embedding is recorded as spend (CV22.DS9.TS2 D1).
+   *
+   * A FUNCTION, never a database handle, and the distinction is the control:
+   * the `llm_calls`-only connection lives in `main.ts` and is never reachable
+   * from a tool, so no tool -- present or future -- can write an
+   * agent-influenced value into the ledger. Omitted, nothing is recorded and
+   * US2's read-only posture stands unchanged.
+   */
+  embeddingLedger?: (info: EmbeddingAttemptInfo) => void;
+  /** Absolute mirror home, for extension resolution. Omit to disable fan-out. */
+  mirrorHome?: string;
+  /** Absolute database path, handed to extension providers. */
+  databasePath?: string;
+  user?: string;
+  /** Frozen clock for the ranker, used by the parity harness. */
+  frozenNowMs?: number;
+}
+
+function toolJson(value: unknown): string {
+  return pythonJson(value, { indent: 2 });
+}
+
+function argument(args: unknown, key: string): unknown {
+  if (args === null || typeof args !== "object" || Array.isArray(args)) return undefined;
+  return (args as Record<string, unknown>)[key];
+}
+
+function pythonInt(value: unknown, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === "number") return Math.trunc(value);
+  if (typeof value === "string") {
+    const parsed = Number(value.trim());
+    if (Number.isFinite(parsed)) return Math.trunc(parsed);
+    throw new Error(`invalid literal for int() with base 10: '${value}'`);
+  }
+  if (typeof value === "boolean") return value ? 1 : 0;
+  throw new Error(`int() argument must be a string or a number, not '${typeof value}'`);
+}
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * Port of `_search_memories`.
+ *
+ * With a `query`: hybrid search, then the ranked ids mapped back to full rows.
+ * Without: the first of `journey`, `layer`, `type` that is present, sliced to
+ * `limit`; none of them is an error. Python's order of preference is exactly
+ * this, and the error text is its text.
+ */
+export async function searchMemoriesTool(
+  db: Database,
+  args: unknown,
+  runtime: ToolRuntime,
+): Promise<string> {
+  const query = argument(args, "query");
+  const limit = pythonInt(argument(args, "limit"), 5);
+  const memoryType = optionalText(argument(args, "type"));
+  const layer = optionalText(argument(args, "layer"));
+  const journey = optionalText(argument(args, "journey"));
+
+  if (query) {
+    const ranked = await searchMemories(db, {
+      query: String(query),
+      limit,
+      memoryType: memoryType ?? null,
+      layer: layer ?? null,
+      journey: journey ?? null,
+      provider: runtime.embeddingProvider,
+      // AI-12: an agent searching on its own behalf is not a genuine context
+      // load, so it must not teach the ranker. Python's MCP handler passes
+      // log_access=False for exactly this reason.
+      logAccess: false,
+      // Spend IS recorded, through the sink rather than through this handle
+      // (TS2 D1): the tools' database is read-only at the driver level, and the
+      // ledger connection it never sees can form no statement but the append.
+      // Without a sink, nothing is written -- US2's posture, unchanged.
+      recordEmbeddingLedger: runtime.embeddingLedger ?? false,
+      ...(runtime.frozenNowMs === undefined ? {} : { frozenNowMs: runtime.frozenNowMs }),
+    });
+    const rows = memoriesByIds(
+      db,
+      ranked.map((result) => result.id),
+    );
+    const byId = new Map(rows.map((row) => [row.id, row]));
+    return toolJson(
+      ranked.map((result) => {
+        const row = byId.get(result.id);
+        return {
+          ...(row ?? emptyMemoryDto(result.id)),
+          // Python types the score as float; a whole score renders 1.0, not 1.
+          score: pyFloat(result.score),
+        };
+      }),
+    );
+  }
+
+  let rows: MemoryDto[];
+  if (journey) rows = memoriesByFilter(db, "journey", journey);
+  else if (layer) rows = memoriesByFilter(db, "layer", layer);
+  else if (memoryType) rows = memoriesByFilter(db, "memory_type", memoryType);
+  else throw new Error("provide 'query' or one of 'type' / 'layer' / 'journey'");
+
+  return toolJson(rows.slice(0, Math.max(0, limit)));
+}
+
+function emptyMemoryDto(id: string): MemoryDto {
+  return {
+    id,
+    title: null,
+    memory_type: null,
+    layer: null,
+    journey: null,
+    tags: null,
+    content: null,
+  };
+}
+
+/**
+ * Port of `_mirror_context`.
+ *
+ * Deliberately not the Mirror Mode load: that one activates the mode and
+ * mutates sticky defaults. This is the side-effect-free context builder, and it
+ * keeps `load_mirror_context`'s defaults -- including reinforcement, because
+ * unlike an agent search this IS a genuine context load (AI-12).
+ *
+ * Extension context is resolved through the same `collectExtensionContext` the
+ * front door uses (plan D4), not a second reading of the `mirror-context-v1`
+ * contract. The agent-supplied `query` reaches every installed provider, which
+ * the DS9 threat model names as the fan-out path.
+ */
+export async function mirrorContextTool(
+  db: Database,
+  args: unknown,
+  runtime: ToolRuntime,
+): Promise<string> {
+  const persona = optionalText(argument(args, "persona"));
+  const journey = optionalText(argument(args, "journey"));
+  const query = optionalText(argument(args, "query"));
+
+  const extensionContext =
+    runtime.mirrorHome && runtime.databasePath
+      ? collectExtensionContext(db, {
+          mirrorHome: runtime.mirrorHome,
+          databasePath: runtime.databasePath,
+          personaId: persona ?? null,
+          journeyId: journey ?? null,
+          user: runtime.user ?? "",
+          query: query ?? null,
+        }).rendered
+      : "";
+
+  return loadMirrorContext(db, {
+    persona: persona ?? null,
+    journey: journey ?? null,
+    query: query ?? null,
+    embeddingProvider: runtime.embeddingProvider,
+    // TS1: attachment search is the tool's paid path and neither engine recorded it.
+    // Same sink as `search_memories`, so one window counts the whole surface.
+    ...(runtime.embeddingLedger ? { embeddingLedger: runtime.embeddingLedger } : {}),
+    extensionContext,
+  });
+}

package/ts/src/mcp/wire.ts

@@ -0,0 +1,8 @@
+// Kept as the US1 call site's name; the rules live in payload.ts (US2 D8).
+//
+// US1 shipped this module with its own copy of the separator logic. US2 needed
+// the same semantics with `indent=2` and a float rule, so the two were folded
+// into one encoder rather than maintained twice. This re-export keeps US1's
+// imports and tests unmoved.
+
+export { encodeJsonLine } from "./payload.ts";

package/ts/src/memory/journal.ts

@@ -0,0 +1,180 @@
+/**
+ * `journal` — CV22.DS7.US11 plateau 3.
+ *
+ * Records a journal entry: classify it through the model, then write the memory
+ * with its embedding. CR068 found this leaf unowned — US2 sent it to US5, US5
+ * was re-scoped without it, and the ledger reported the family `3/3 done` while
+ * Python answered every call.
+ *
+ * Graded by `ts/test/goldens/journal.golden.json`. The corpus pins several
+ * Python behaviours that a reasonable port gets wrong:
+ *
+ *   - **AI-24 layer coercion.** A model layer outside `self|ego|shadow` becomes
+ *     `ego` rather than reaching the write unchecked (CV9.E2.S23/S25).
+ *   - **The non-JSON fallback** is `{title: content[:60], layer: "ego",
+ *     tags: []}`, and the 60 is CODE POINTS.
+ *   - **`", ".join(tags)` over a STRING iterates characters.** When the model
+ *     returns `"not-a-list"`, Python's receipt reads `n, o, t, -, a, ...`. It
+ *     looks like a bug and is reproduced deliberately: the receipt is what a
+ *     user sees, and the row stores the same odd value.
+ *   - **The embedding is generated BEFORE the row is inserted**, so a failing
+ *     embedding persists NOTHING — while the classification and the (unpriced)
+ *     embedding ledger rows already exist. Insert-then-embed passes every other
+ *     case and fails this one.
+ */
+
+import type { WritableDatabase } from "#db/database.ts";
+import { createMemoryRow } from "#memory/memoryWrite.ts";
+import { addEmbeddingProvenance } from "#providers/embedding.ts";
+import { memoryEmbedText } from "#soul/harvest.ts";
+import { pythonJsonDumpsEnsureAscii } from "#util/pyGenerators.ts";
+import { sliceCodePoints } from "#util/pythonText.ts";
+
+/** Python `VALID_MEMORY_LAYERS`. */
+const VALID_MEMORY_LAYERS = new Set(["self", "ego", "shadow"]);
+
+/** Python's `layer_labels`, with the raw layer as its own fallback. */
+const LAYER_LABELS: Record<string, string> = {
+  self: "Self (identity)",
+  ego: "Ego (operational)",
+  shadow: "Shadow (tension)",
+};
+
+export interface JournalClassification {
+  title: string;
+  layer: string;
+  tags: unknown;
+}
+
+/**
+ * Python `classify_journal_entry`'s post-processing, given a raw model
+ * response body. Kept separate from transport so it can be graded directly.
+ */
+export function interpretJournalClassification(
+  responseContent: string,
+  content: string,
+  parseJson: (raw: string) => unknown,
+): JournalClassification {
+  const data = parseJson(responseContent);
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    // Python: `{"title": content[:60], "layer": "ego", "tags": []}`.
+    return { title: sliceCodePoints(content, 60), layer: "ego", tags: [] };
+  }
+  const record = data as Record<string, unknown>;
+  const rawLayer = "layer" in record ? record.layer : "ego";
+  const layer =
+    typeof rawLayer === "string" && VALID_MEMORY_LAYERS.has(rawLayer) ? rawLayer : "ego";
+  const title = "title" in record ? record.title : sliceCodePoints(content, 60);
+  return {
+    title: typeof title === "string" ? title : String(title),
+    layer,
+    tags: "tags" in record ? record.tags : [],
+  };
+}
+
+/**
+ * Python `", ".join(tags)`.
+ *
+ * `str.join` iterates its argument. Over a list that is the elements; over a
+ * STRING it is the characters, which is why a model returning `"not-a-list"`
+ * yields `n, o, t, -, a, -, l, i, s, t`. Reproduced, not corrected.
+ *
+ * The CLI reaches this only after `json.loads(memory.tags)`, so the value seen
+ * here is whatever round-tripped through the stored JSON.
+ */
+export function renderJournalTags(tags: unknown): string {
+  if (typeof tags === "string") return Array.from(tags).join(", ");
+  if (Array.isArray(tags))
+    return tags.map((tag) => (typeof tag === "string" ? tag : String(tag))).join(", ");
+  return "";
+}
+
+/** Python: `json.dumps(tags) if tags else None` — an empty list stores NULL. */
+function storedTags(tags: unknown): string | null {
+  if (tags === null || tags === undefined) return null;
+  if (Array.isArray(tags) && tags.length === 0) return null;
+  if (typeof tags === "string" && tags.length === 0) return null;
+  return pythonJsonDumpsEnsureAscii(tags);
+}
+
+export interface AddJournalInput {
+  content: string;
+  journey?: string | null;
+  classification: JournalClassification;
+}
+
+export interface AddJournalDeps {
+  newId: () => string;
+  nowIso: string;
+  /** Throws when the provider fails; called BEFORE the row is inserted. */
+  embed: (text: string) => Uint8Array;
+}
+
+export interface AddJournalResult {
+  memoryId: string;
+  title: string;
+  layer: string;
+  tags: unknown;
+}
+
+/**
+ * Python `MemoryService.add_journal` → `add_memory` for the journal path.
+ *
+ * The embedding is computed first, deliberately: `add_memory` embeds before it
+ * builds the row, so a provider failure leaves no memory behind.
+ */
+export function addJournal(
+  db: WritableDatabase,
+  input: AddJournalInput,
+  deps: AddJournalDeps,
+): AddJournalResult {
+  const { title, layer, tags } = input.classification;
+
+  const embedding = deps.embed(memoryEmbedText(title, input.content, null));
+
+  const memoryId = deps.newId();
+  createMemoryRow(db, {
+    id: memoryId,
+    conversationId: null,
+    memoryType: "journal",
+    layer,
+    title,
+    content: input.content,
+    context: null,
+    journey: input.journey ?? null,
+    persona: null,
+    tags: storedTags(tags),
+    createdAt: deps.nowIso,
+    embedding,
+    metadata: addEmbeddingProvenance(null),
+  });
+
+  return { memoryId, title, layer, tags };
+}
+
+/** Python's printed receipt, line for line. */
+export function renderJournalReceipt(
+  result: AddJournalResult,
+  journey: string | null | undefined,
+  storedTagsJson: string | null,
+): string {
+  const parsedTags: unknown = storedTagsJson === null ? [] : safeJsonParse(storedTagsJson);
+  const lines = [
+    "📓 Journal entry recorded",
+    `   Title: ${result.title}`,
+    `   Layer: ${LAYER_LABELS[result.layer] ?? result.layer}`,
+    `   Tags: ${renderJournalTags(parsedTags)}`,
+  ];
+  if (journey) lines.push(`   Journey: ${journey}`);
+  lines.push(`   ID: ${result.memoryId.slice(0, 8)}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** Python's `try: json.loads(...) except (JSONDecodeError, TypeError): []`. */
+function safeJsonParse(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return [];
+  }
+}

package/ts/src/memory/listing.ts

@@ -0,0 +1,107 @@
+// Memory listing parity port (CV22.DS2.US3).
+//
+// A faithful TypeScript port of Python `Store.list_recent_memory_summaries` and
+// `Store.count_memories_by_type` (`src/memory/storage/memories.py`). Following
+// the database-seam philosophy, the ordering is pushed down to SQLite
+// (`ORDER BY created_at DESC`) — the TS unit is a query builder + row→summary
+// mapper, not a re-implementation of SQLite's sort. The `--search` listing path
+// is out of scope here: it reuses the US1 hybrid ranker.
+
+import type { Database, SqlValue } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+/** The listing projection, mirroring the Python `MemorySummary` DTO. */
+export interface MemorySummary {
+  id: string;
+  memory_type: string;
+  layer: string;
+  title: string;
+  content: string;
+  context: string | null;
+  journey: string | null;
+  persona: string | null;
+  tags: string | null;
+  created_at: string;
+}
+
+/** Optional equality filters and limit for the recent-memories read. */
+export interface ListRecentFilters {
+  limit?: number;
+  memoryType?: string | null;
+  layer?: string | null;
+  journey?: string | null;
+}
+
+const SUMMARY_COLUMNS =
+  "id, memory_type, layer, title, content, context, journey, persona, tags, created_at";
+
+/**
+ * Build the parameterized recent-memories query, mirroring the Python builder:
+ * a `1=1` seed, one `col = ?` clause per provided filter (in
+ * type → layer → journey order), `ORDER BY created_at DESC`, and a trailing
+ * `LIMIT ?`. Params are ordered to match the placeholders.
+ */
+export function buildListRecentQuery(filters: ListRecentFilters = {}): {
+  sql: string;
+  params: SqlValue[];
+} {
+  const { limit = 20, memoryType = null, layer = null, journey = null } = filters;
+  const conditions = ["1=1"];
+  const params: SqlValue[] = [];
+  if (memoryType) {
+    conditions.push("memory_type = ?");
+    params.push(memoryType);
+  }
+  if (layer) {
+    conditions.push("layer = ?");
+    params.push(layer);
+  }
+  if (journey) {
+    conditions.push("journey = ?");
+    params.push(journey);
+  }
+  params.push(limit);
+  const sql =
+    `SELECT ${SUMMARY_COLUMNS} FROM memories ` +
+    `WHERE ${conditions.join(" AND ")} ORDER BY created_at DESC LIMIT ?`;
+  return { sql, params };
+}
+
+function toSummary(row: Record<string, unknown>): MemorySummary {
+  return {
+    id: requireString(row, "id"),
+    memory_type: requireString(row, "memory_type"),
+    layer: requireString(row, "layer"),
+    title: requireString(row, "title"),
+    content: requireString(row, "content"),
+    context: optionalString(row, "context"),
+    journey: optionalString(row, "journey"),
+    persona: optionalString(row, "persona"),
+    tags: optionalString(row, "tags"),
+    created_at: requireString(row, "created_at"),
+  };
+}
+
+/** Return recent memory summaries with optional equality filters, newest first. */
+export function listRecentMemorySummaries(
+  db: Database,
+  filters: ListRecentFilters = {},
+): MemorySummary[] {
+  const { sql, params } = buildListRecentQuery(filters);
+  return db
+    .prepare(sql)
+    .all(...params)
+    .map(toSummary);
+}
+
+/**
+ * Return memory counts grouped by type. SQLite leaves `GROUP BY` order
+ * unspecified, so — like the Python CLI, which sorts before display — callers
+ * compare these as a map/sorted set, not as an ordered list.
+ */
+export function countMemoriesByType(db: Database): [string, number][] {
+  return db
+    .prepare("SELECT memory_type, COUNT(*) as count FROM memories GROUP BY memory_type")
+    .all()
+    .map((row) => [requireString(row, "memory_type"), Number(row.count)] as [string, number]);
+}