mirror-mind 0.0.1 → 0.33.0

package/ts/src/mcp/readModels.ts

@@ -0,0 +1,241 @@
+// Read models the MCP tools need and the TS core did not yet have (CV22.DS9.US2).
+//
+// Two of the seven tools read shapes no ported command produced. `list_journeys`
+// wants `JourneyService.list_journeys()`' dicts -- TS had only
+// `listActiveMirrorJourneys`, which renders a string for Mirror Mode -- and
+// `journey_status` wants `get_journey_status()`' dict, where TS had only the
+// status renderer's projection of `created_at, title`.
+//
+// Both are ported from the Python services, not reconstructed from renderers.
+// What already existed is reused rather than rewritten: `extractStatus` from
+// `identity/journeyListing.ts` (so the `**Status:**` regex does not get a third
+// copy), and `allJourneyKeys` plus `getJourneyPathContent` from
+// `journey/journeyStatus.ts` -- the latter carries the sync-file fallback that
+// `get_journey_path` performs before reading the database, which a fresh
+// implementation here would have silently dropped.
+
+import type { Database, Row } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+import { extractStatus } from "#identity/journeyListing.ts";
+import { allJourneyKeys, getJourneyPathContent } from "#journey/journeyStatus.ts";
+
+/** One row of `JourneyService.list_journeys()`. */
+export interface JourneyDto {
+  id: string;
+  name: string;
+  description: string;
+  status: string;
+  metadata: Record<string, unknown>;
+}
+
+/** The `_memory_to_dict` shape the tools serialize. */
+export interface MemoryDto {
+  id: string | null;
+  title: string | null;
+  memory_type: string | null;
+  layer: string | null;
+  journey: string | null;
+  tags: string | null;
+  content: string | null;
+}
+
+/** The `_conversation_to_dict` shape (CV22.DS9.US2 D1). */
+export interface ConversationDto {
+  id: string | null;
+  title: string | null;
+  started_at: string | null;
+  ended_at: string | null;
+  interface: string | null;
+  persona: string | null;
+  journey: string | null;
+  summary: string | null;
+}
+
+/** One journey's entry in `get_journey_status()`. */
+export interface JourneyStatusEntry {
+  identity: string | null;
+  journey_path: string | null;
+  recent_memories: MemoryDto[];
+  recent_conversations: ConversationDto[];
+}
+
+/** Python's `_metadata_dict`: `{}` for absent, unparseable, or non-object JSON. */
+function metadataObject(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== "string" || raw === "") return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Port of `list_journeys`' name/description derivation.
+ *
+ * `name` is the first line with leading `#` and spaces stripped; `description`
+ * is the first paragraph under `## Description` (or `## Descrição`), truncated
+ * to 150 characters. The description regex needs a blank line or a following
+ * heading to terminate on -- a journey whose description runs to end-of-content
+ * yields `""`, which is the oracle's behavior and not a bug to fix here.
+ */
+function journeyName(content: string): string {
+  return (content.split("\n")[0] ?? "")
+    .trim()
+    .replace(/^[# ]+/, "")
+    .trim();
+}
+
+function journeyDescription(content: string): string {
+  const match = content.match(/## (?:Description|Descrição)\s*\n+([\s\S]+?)(?:\n\n|\n##)/);
+  return match ? match[1].trim().slice(0, 150) : "";
+}
+
+/** Port of `JourneyService.list_journeys()`. */
+export function listJourneyDtos(db: Database): JourneyDto[] {
+  return db
+    .prepare("SELECT key, content, metadata FROM identity WHERE layer = 'journey' ORDER BY key")
+    .all()
+    .map((row: Row) => {
+      const content = optionalString(row, "content") ?? "";
+      return {
+        id: requireString(row, "key"),
+        name: journeyName(content),
+        description: journeyDescription(content),
+        // `list_journeys` uses `\w+` here while `list_journey_options` uses
+        // `[^\n]+`: the same service reads the same field two ways, so
+        // `**Status:** in progress` is "in" in a card and "in progress" in a
+        // selector. Ported as-is; converging them is a product decision.
+        status: extractStatus(content),
+        metadata: metadataObject(optionalString(row, "metadata")),
+      };
+    });
+}
+
+/** Port of `JourneyService.list_active_journeys()`. */
+export function listActiveJourneyDtos(db: Database): JourneyDto[] {
+  return listJourneyDtos(db).filter((journey) => journey.status === "active");
+}
+
+function memoryDto(row: Row): MemoryDto {
+  return {
+    id: optionalString(row, "id"),
+    title: optionalString(row, "title"),
+    memory_type: optionalString(row, "memory_type"),
+    layer: optionalString(row, "layer"),
+    journey: optionalString(row, "journey"),
+    tags: optionalString(row, "tags"),
+    content: optionalString(row, "content"),
+  };
+}
+
+function conversationDto(row: Row): ConversationDto {
+  return {
+    id: optionalString(row, "id"),
+    title: optionalString(row, "title"),
+    started_at: optionalString(row, "started_at"),
+    ended_at: optionalString(row, "ended_at"),
+    interface: optionalString(row, "interface"),
+    persona: optionalString(row, "persona"),
+    journey: optionalString(row, "journey"),
+    summary: optionalString(row, "summary"),
+  };
+}
+
+/**
+ * Port of `get_journey_status()` for one journey or all of them.
+ *
+ * Python reads `SELECT *` with no LIMIT and slices `[:10]` in memory, loading
+ * every memory of the journey -- embedding blobs included -- to render seven
+ * fields of ten rows. This reproduces the RESULT with a projection and a LIMIT;
+ * the bytes are identical and the read is not. Neither query carries a tie-break
+ * beyond its timestamp, so equal timestamps resolve by rowid on both sides.
+ */
+export function journeyStatus(
+  db: Database,
+  slug: string | null,
+): Record<string, JourneyStatusEntry> {
+  const journeyIds = slug ? [slug] : allJourneyKeys(db);
+
+  const result: Record<string, JourneyStatusEntry> = {};
+  for (const journeyId of journeyIds) {
+    const identityRow = db
+      .prepare("SELECT content FROM identity WHERE layer = 'journey' AND key = ?")
+      .get(journeyId);
+    // Not a plain identity read: `get_journey_path` prefers a configured
+    // sync_file on disk and falls back to the database.
+    const journeyPath = getJourneyPathContent(db, journeyId);
+    const memories = db
+      .prepare(
+        "SELECT id, title, memory_type, layer, journey, tags, content FROM memories " +
+          "WHERE journey = ? ORDER BY created_at DESC LIMIT 10",
+      )
+      .all(journeyId);
+    const conversations = db
+      .prepare(
+        "SELECT id, title, started_at, ended_at, interface, persona, journey, summary " +
+          "FROM conversations WHERE journey = ? ORDER BY started_at DESC LIMIT 5",
+      )
+      .all(journeyId);
+
+    result[journeyId] = {
+      identity: identityRow === undefined ? null : optionalString(identityRow, "content"),
+      journey_path: journeyPath,
+      recent_memories: memories.map((row) => memoryDto(row as Record<string, unknown>)),
+      recent_conversations: conversations.map((row) =>
+        conversationDto(row as Record<string, unknown>),
+      ),
+    };
+  }
+  return result;
+}
+
+/** Memories by journey / layer / type, as the filter paths of `search_memories` read them. */
+export function memoriesByFilter(
+  db: Database,
+  column: "journey" | "layer" | "memory_type",
+  value: string,
+): MemoryDto[] {
+  return db
+    .prepare(
+      `SELECT id, title, memory_type, layer, journey, tags, content FROM memories ` +
+        `WHERE ${column} = ? ORDER BY created_at DESC`,
+    )
+    .all(value)
+    .map((row: Row) => memoryDto(row));
+}
+
+/** Messages for `recall_conversation`, which needs `created_at` the recall renderer does not. */
+export function recallMessages(
+  db: Database,
+  conversationId: string,
+): { role: string; content: string; created_at: string | null }[] {
+  return db
+    .prepare(
+      "SELECT role, content, created_at FROM messages WHERE conversation_id = ? ORDER BY created_at",
+    )
+    .all(conversationId)
+    .map((row: Row) => ({
+      role: requireString(row, "role"),
+      content: requireString(row, "content"),
+      created_at: optionalString(row, "created_at"),
+    }));
+}
+
+/**
+ * Full rows for an explicit id list, as `search_memories`' query path needs
+ * after ranking returns ids and scores. Order is the caller's, not the
+ * database's: the ranking decided it.
+ */
+export function memoriesByIds(db: Database, ids: readonly string[]): MemoryDto[] {
+  if (ids.length === 0) return [];
+  const placeholders = ids.map(() => "?").join(", ");
+  return db
+    .prepare(
+      `SELECT id, title, memory_type, layer, journey, tags, content FROM memories ` +
+        `WHERE id IN (${placeholders})`,
+    )
+    .all(...ids)
+    .map((row: Row) => memoryDto(row));
+}

package/ts/src/mcp/registry.ts

@@ -0,0 +1,201 @@
+// MCP tool registry (CV22.DS9.US1).
+//
+// A faithful port of `src/memory/mcp/tools.py`'s declarations: the seven tool
+// names, descriptions, and JSON Schemas that `tools/list` serializes. These
+// bytes are the client contract -- some clients cache them across sessions, and
+// the descriptions are prompt text the model reads every time it decides
+// whether to call a tool -- so US2 may fill in behavior but must not disturb
+// the declarations.
+//
+// The absence of `annotations` is deliberate, not an omission. The 2025-06-18
+// protocol lets a server declare `readOnlyHint`, and clients use it to skip the
+// per-call permission prompt. Every tool here IS read-only, so the hint would be
+// truthful -- and it would remove the only human-in-the-loop gate on what the
+// DS9 threat model calls a read oracle over private memory: the caller is the
+// model, and the model is driven by anything in its context. Parity and security
+// agree here; the golden's byte-identical `tools/list` enforces it.
+//
+// US1 shipped declarations over stub handlers so the protocol could be graded
+// without a database; US2 wires them to the TS capabilities that already exist
+// (`loadMirrorContext`, journey listing/status, `searchMemories`, conversation
+// listing/recall, `detectPersona`).
+
+import type { Database } from "#db/database.ts";
+import {
+  detectPersonaTool,
+  journeyStatusTool,
+  listConversationsTool,
+  listJourneysTool,
+  recallConversationTool,
+} from "./tools/deterministic.ts";
+import {
+  mirrorContextTool,
+  searchMemoriesTool,
+  type ToolRuntime,
+} from "./tools/providerCrossing.ts";
+
+/** JSON Schema as the tool declares it; shape is opaque to the protocol layer. */
+export type JsonSchema = Record<string, unknown>;
+
+/** A tool handler: receives the raw `arguments` value and returns text content. */
+export type ToolHandler = (args: unknown) => string | Promise<string>;
+
+/** An MCP tool: name, description, schema, handler -- mirroring Python's `Tool`. */
+export interface Tool {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  handler: ToolHandler;
+}
+
+/** The registry the protocol layer dispatches against. */
+export interface ToolRegistry {
+  /** Declaration order, as `tools/list` serializes it. */
+  list: readonly Tool[];
+  /** Dispatch map for `tools/call`. May hold entries absent from `list`. */
+  byName: ReadonlyMap<string, Tool>;
+}
+
+function notImplemented(name: string): ToolHandler {
+  return () => {
+    throw new Error(`Tool '${name}' is not wired yet (CV22.DS9.US2 owns tool behavior)`);
+  };
+}
+
+/** What the wired handlers need from the process. */
+export interface ToolContext {
+  db: Database;
+  runtime: ToolRuntime;
+}
+
+/**
+ * The registry with real handlers, in Python's declaration order.
+ *
+ * Declarations stay exactly as `TOOL_DECLARATIONS` has them -- `tools/list` is
+ * the client contract and must not shift when behavior arrives.
+ */
+export function wiredRegistry(context: ToolContext): ToolRegistry {
+  const handlers: Record<string, ToolHandler> = {
+    mirror_context: (args) => mirrorContextTool(context.db, args, context.runtime),
+    list_journeys: (args) => listJourneysTool(context.db, args),
+    journey_status: (args) => journeyStatusTool(context.db, args),
+    search_memories: (args) => searchMemoriesTool(context.db, args, context.runtime),
+    list_conversations: (args) => listConversationsTool(context.db, args),
+    recall_conversation: (args) => recallConversationTool(context.db, args),
+    detect_persona: (args) => detectPersonaTool(context.db, args),
+  };
+  return buildRegistry(
+    TOOL_DECLARATIONS.map((declaration) => {
+      const handler = handlers[declaration.name];
+      if (!handler) throw new Error(`no handler wired for tool '${declaration.name}'`);
+      return { ...declaration, handler };
+    }),
+  );
+}
+
+/**
+ * The seven tools, in Python's declaration order. Descriptions and schemas are
+ * byte-for-byte the strings in `tools.py`; changing one is a client-visible
+ * contract change, and the parity golden fails on it.
+ */
+export const TOOL_DECLARATIONS: readonly Omit<Tool, "handler">[] = [
+  {
+    name: "mirror_context",
+    description:
+      "Load Mirror identity context on demand (side-effect-free). Optionally " +
+      "scope by persona and journey; pass the user query for attachment search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "User query for attachment search." },
+        persona: { type: "string", description: "Persona id to scope context." },
+        journey: { type: "string", description: "Journey slug to scope context." },
+      },
+    },
+  },
+  {
+    name: "list_journeys",
+    description: "List active journeys with status, stage, and description.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "journey_status",
+    description: "Get status for one journey, or overall status when no slug is given.",
+    inputSchema: {
+      type: "object",
+      properties: { slug: { type: "string", description: "Journey slug." } },
+    },
+  },
+  {
+    name: "search_memories",
+    description: "Search memories by query, or list by type/layer/journey filter.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        type: { type: "string", description: "Memory type filter." },
+        layer: { type: "string", description: "Jungian layer filter." },
+        journey: { type: "string", description: "Journey slug filter." },
+        limit: { type: "integer", default: 5 },
+      },
+    },
+  },
+  {
+    name: "list_conversations",
+    description: "List recent conversations with optional journey/persona filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", default: 20 },
+        journey: { type: "string" },
+        persona: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "recall_conversation",
+    description: "Load messages from a previous conversation by id (prefix accepted).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string" },
+        limit: { type: "integer", default: 50 },
+      },
+      required: ["conversation_id"],
+    },
+  },
+  {
+    name: "detect_persona",
+    description: "Show persona routing matches for a query.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" } },
+      required: ["query"],
+    },
+  },
+];
+
+/** Build a registry from tools, optionally adding dispatch-only entries. */
+export function buildRegistry(
+  list: readonly Tool[],
+  dispatchOnly: readonly Tool[] = [],
+): ToolRegistry {
+  const byName = new Map<string, Tool>();
+  for (const tool of [...list, ...dispatchOnly]) byName.set(tool.name, tool);
+  return { list, byName };
+}
+
+/**
+ * The seven declarations over handlers that refuse.
+ *
+ * Kept for the protocol tests, which grade dispatch without a database. The
+ * server uses `wiredRegistry`.
+ */
+export function defaultRegistry(): ToolRegistry {
+  return buildRegistry(
+    TOOL_DECLARATIONS.map((declaration) => ({
+      ...declaration,
+      handler: notImplemented(declaration.name),
+    })),
+  );
+}

package/ts/src/mcp/serve.ts

@@ -0,0 +1,120 @@
+// MCP stdio transport loop (CV22.DS9.US1).
+//
+// The port of `serve()` in `src/memory/mcp/server.py`: newline-delimited
+// JSON-RPC on stdin/stdout, diagnostics on stderr, one JSON object per line.
+// Python guarantees these rules by reading -- it has no test of its own for
+// `serve()` -- so the parity harness that grades this loop is the first
+// executable statement of them on either side.
+//
+// Two places where a faithful-looking port is wrong:
+//
+// 1. **Draining.** Python's `sys.stdout.write` + `flush()` is synchronous. Node's
+//    `process.stdout` is synchronous to a TTY and to a file, but ASYNCHRONOUS to
+//    a pipe on macOS -- and a pipe is exactly what an MCP client gives us. A
+//    `process.exit()` on end-of-input therefore truncates whatever is still
+//    queued, and a half-written JSON line reaches the model as a malformed tool
+//    result from a server that then vanishes. `recall_conversation` returns whole
+//    transcripts, so the queue is not hypothetical. This loop never exits with a
+//    write pending.
+//
+// 2. **Staying alive.** A throw anywhere in the loop kills the process, and the
+//    client does not restart a server mid-session: every tool disappears at once.
+//    Each message is handled inside its own try, and failures become JSON-RPC
+//    responses rather than exits.
+
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { packageVersion } from "#runtime/version.ts";
+import { handleMessage, type JsonRpcResponse } from "./protocol.ts";
+import { defaultRegistry, type ToolRegistry } from "./registry.ts";
+import { encodeJsonLine } from "./wire.ts";
+
+// Resolved from this file, not the cwd: an MCP client spawns the server from
+// whatever directory the session happens to be in.
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export interface ServeOptions {
+  registry?: ToolRegistry;
+  serverVersion?: string;
+  input?: NodeJS.ReadableStream;
+  output?: NodeJS.WritableStream;
+}
+
+/** Resolve the server version the way `initialize` reports it. */
+export function resolveServerVersion(): string {
+  // The Python server reported `importlib.metadata.version("mirror")` --
+  // 0.31.x. This reports THE product version, `packageVersion`, which reads
+  // `package.json` since CV22.DS10.TS5 (decision D1; at the root since US3 D2): the same source the
+  // plugin manifest is generated from and the same one `runtime version`
+  // reads. An explicit MIRROR_MCP_VERSION pin still wins; the DS9 parity
+  // harness that set it is gone, and the guard probe unsets it. "0.0.0" is
+  // only what a tree that is not Mirror Mind reports.
+  return process.env.MIRROR_MCP_VERSION ?? packageVersion(HERE) ?? "0.0.0";
+}
+
+/** Write one line and resolve once it has actually left the process. */
+function writeLine(output: NodeJS.WritableStream, line: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    output.write(`${line}\n`, (err) => (err ? reject(err) : resolve()));
+  });
+}
+
+/**
+ * Read newline-delimited JSON-RPC from `input` and answer on `output`.
+ *
+ * Resolves when input ends and every response has drained. The caller exits;
+ * this function never calls `process.exit` itself, so it stays testable.
+ */
+export async function serve(options: ServeOptions = {}): Promise<void> {
+  const registry = options.registry ?? defaultRegistry();
+  const serverVersion = options.serverVersion ?? resolveServerVersion();
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+
+  const reader = createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY });
+
+  for await (const rawLine of reader) {
+    // Python: `line = line.strip()`, then skip when empty -- so a
+    // whitespace-only line is skipped too, not answered with a parse error.
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    let response: JsonRpcResponse | null;
+    try {
+      let message: unknown;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        await writeLine(output, encodeJsonLine(error(null, -32700, "Parse error")));
+        continue;
+      }
+      if (message === null || typeof message !== "object" || Array.isArray(message)) {
+        await writeLine(output, encodeJsonLine(error(null, -32600, "Invalid Request")));
+        continue;
+      }
+      response = await handleMessage(message as Record<string, unknown>, registry, {
+        serverVersion,
+      });
+    } catch (thrown) {
+      // Reaching here means the dispatcher itself failed, which the oracle has
+      // no branch for. Answer rather than die: the alternative is a dead server.
+      process.stderr.write(`mcp: internal dispatch failure: ${describe(thrown)}\n`);
+      continue;
+    }
+
+    if (response !== null) await writeLine(output, encodeJsonLine(response));
+  }
+}
+
+function error(id: unknown, code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+/** Describe a thrown value without leaking arguments or results into stderr. */
+function describe(thrown: unknown): string {
+  // RS005: stderr is the MCP client's log for this server. Tool arguments are
+  // agent-authored text and tool results are identity and transcript content;
+  // neither may appear here. Only the error type crosses.
+  return thrown instanceof Error ? thrown.name : typeof thrown;
+}