@yugabytedb/meko-mcp 1.0.3

package/assets/hooks-handlers/lib/capture.js

@@ -0,0 +1,863 @@
+#!/usr/bin/env node
+/**
+ * capture.js — Unified conversation capture for Meko MCP plugin.
+ *
+ * Handles transcript parsing, watermark management, and MCP API calls.
+ * No external dependencies — uses only Node.js built-ins (fs, http/https, crypto).
+ *
+ * Usage (called by hook shell wrappers):
+ *   node capture.js session-start # creates conversation + watermark, outputs additionalContext
+ *   node capture.js pre-compact   # reads hook input from stdin
+ *   node capture.js session-end   # reads hook input from stdin
+ *
+ * Environment:
+ *   MEKO_MCP_URL       MCP server URL (default: http://localhost:8000/mcp)
+ *   MEKO_AGENT_ID      Agent identifier (default: claude_code)
+ *   MEKO_API_KEY        API key for Cloud Meko auth (optional, omit for local)
+ *   MEKO_API_TIMEOUT   Request timeout in seconds (default: 10)
+ *   MEKO_WATERMARK_DIR Watermark directory (default: ~/.claude/meko-capture)
+ */
+
+const fs = require("fs");
+const path = require("path");
+const http = require("http");
+const https = require("https");
+
+// --- Config ---
+
+const MEKO_MCP_URL = process.env.MEKO_MCP_URL || "http://localhost:8000/mcp";
+const MEKO_AGENT_ID = process.env.MEKO_AGENT_ID || "claude_code";
+const MEKO_API_KEY = process.env.MEKO_API_KEY || "";
+const MEKO_API_TIMEOUT = parseInt(process.env.MEKO_API_TIMEOUT || "10", 10) * 1000;
+const WATERMARK_DIR =
+  process.env.MEKO_WATERMARK_DIR ||
+  path.join(process.env.HOME || "~", ".claude", "meko-capture");
+
+let mcpRequestId = 0;
+let mcpSessionId = null; // MCP Streamable HTTP session ID
+const inflightRequests = new Set(); // tracked so preload timeouts can abort
+
+// --- Transcript parsing ---
+
+function countLines(filePath) {
+  const buf = fs.readFileSync(filePath);
+  let count = 0;
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 0x0a) count++;
+  }
+  if (buf.length > 0 && buf[buf.length - 1] !== 0x0a) count++;
+  return count;
+}
+
+// --- Truncation limits (configurable via env) ---
+
+const MAX_THINKING_LEN = parseInt(process.env.MEKO_MAX_THINKING_LEN || "2000", 10);
+const MAX_TOOL_INPUT_LEN = parseInt(process.env.MEKO_MAX_TOOL_INPUT_LEN || "500", 10);
+const MAX_TOOL_RESULT_LEN = parseInt(process.env.MEKO_MAX_TOOL_RESULT_LEN || "3000", 10);
+
+function truncate(str, max) {
+  if (!str || str.length <= max) return str;
+  return str.slice(0, max) + "... [truncated]";
+}
+
+// --- Content extraction helpers ---
+
+function extractText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => typeof b === "string" || (b && b.type === "text"))
+      .map((b) => (typeof b === "string" ? b : b.text || ""))
+      .join("\n");
+  }
+  return "";
+}
+
+function extractThinking(contentBlocks) {
+  if (!Array.isArray(contentBlocks)) return "";
+  const parts = [];
+  for (const block of contentBlocks) {
+    if (block && block.type === "thinking" && block.thinking) {
+      parts.push(truncate(block.thinking, MAX_THINKING_LEN));
+    }
+  }
+  return parts.join("\n");
+}
+
+function extractToolCalls(contentBlocks) {
+  if (!Array.isArray(contentBlocks)) return "";
+  const parts = [];
+  for (const block of contentBlocks) {
+    if (block && block.type === "tool_use") {
+      const name = block.name || "unknown";
+      let inputStr = "";
+      if (block.input && typeof block.input === "object") {
+        try {
+          inputStr = truncate(JSON.stringify(block.input), MAX_TOOL_INPUT_LEN);
+        } catch {
+          inputStr = "(unserializable)";
+        }
+      }
+      parts.push(`TOOL CALL: ${name}(${inputStr})`);
+    }
+  }
+  return parts.join("\n");
+}
+
+function isToolResultMessage(msg) {
+  if (msg.toolUseResult != null) return true;
+  const content = (msg.message || {}).content;
+  if (Array.isArray(content)) {
+    return content.some((b) => b && b.type === "tool_result");
+  }
+  return false;
+}
+
+function extractToolResultContent(msg) {
+  const parts = [];
+  const content = (msg.message || {}).content;
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && block.type === "tool_result") {
+        const resultContent = block.content;
+        if (typeof resultContent === "string") {
+          parts.push(truncate(resultContent, MAX_TOOL_RESULT_LEN));
+        } else if (Array.isArray(resultContent)) {
+          const text = extractText(resultContent);
+          if (text) parts.push(truncate(text, MAX_TOOL_RESULT_LEN));
+        }
+      }
+    }
+  }
+  // Fallback to toolUseResult summary if no content blocks found
+  if (parts.length === 0 && msg.toolUseResult != null) {
+    const summary =
+      typeof msg.toolUseResult === "string"
+        ? msg.toolUseResult
+        : JSON.stringify(msg.toolUseResult);
+    parts.push(truncate(summary, MAX_TOOL_RESULT_LEN));
+  }
+  return parts.length > 0 ? "TOOL RESULT:\n" + parts.join("\n") : "";
+}
+
+// --- Turn-assembly exchange extraction ---
+
+function extractExchanges(filePath, startLine) {
+  const data = fs.readFileSync(filePath, "utf-8");
+  const lines = data.split("\n");
+
+  // Step 1: Parse relevant lines
+  const entries = [];
+  for (let i = startLine; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    try {
+      const obj = JSON.parse(line);
+      if (obj.type === "user" || obj.type === "assistant") {
+        entries.push(obj);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  // Step 2: Group into exchanges using turn-assembly.
+  // A real user message (no toolUseResult) starts a new exchange.
+  // All subsequent assistant lines and tool-result user lines belong
+  // to that exchange until the next real user message.
+  const exchanges = [];
+  let current = null;
+
+  for (const entry of entries) {
+    if (entry.type === "user" && !isToolResultMessage(entry)) {
+      if (current) exchanges.push(current);
+      current = {
+        userMsg: entry,
+        assistantEntries: [],
+        toolResultEntries: [],
+      };
+    } else if (current) {
+      if (entry.type === "assistant") {
+        current.assistantEntries.push(entry);
+      } else if (entry.type === "user" && isToolResultMessage(entry)) {
+        current.toolResultEntries.push(entry);
+      }
+    }
+  }
+  if (current) exchanges.push(current);
+
+  // Step 3: Build output for each exchange
+  const skipPattern =
+    /^<(system-reminder|command-|local-command|available-deferred)/;
+  const results = [];
+
+  for (const ex of exchanges) {
+    const input = extractText((ex.userMsg.message || {}).content);
+    if (!input || skipPattern.test(input)) continue;
+    if (ex.assistantEntries.length === 0) continue;
+
+    const outputParts = [];
+    const reasoningParts = [];
+
+    for (const aEntry of ex.assistantEntries) {
+      const content = (aEntry.message || {}).content;
+      if (!Array.isArray(content)) continue;
+
+      const text = extractText(content);
+      if (text) outputParts.push(text);
+
+      const thinking = extractThinking(content);
+      if (thinking) reasoningParts.push("THINKING:\n" + thinking);
+
+      const toolCalls = extractToolCalls(content);
+      if (toolCalls) reasoningParts.push(toolCalls);
+    }
+
+    for (const trEntry of ex.toolResultEntries) {
+      const resultText = extractToolResultContent(trEntry);
+      if (resultText) reasoningParts.push(resultText);
+    }
+
+    results.push({
+      user_uuid: ex.userMsg.uuid || "unknown",
+      input: input,
+      output: outputParts.join("\n\n"),
+      reasoning: reasoningParts.join("\n---\n"),
+      timestamp:
+        ex.assistantEntries[ex.assistantEntries.length - 1].timestamp ||
+        ex.userMsg.timestamp ||
+        "",
+    });
+  }
+
+  return results;
+}
+
+// --- Watermark ---
+
+function readWatermark(wmPath) {
+  try {
+    return JSON.parse(fs.readFileSync(wmPath, "utf-8"));
+  } catch {
+    return { conversation_id: "", last_line_number: 0, agent_id: "" };
+  }
+}
+
+function writeWatermark(wmPath, convId, lineNum, agentId) {
+  fs.mkdirSync(path.dirname(wmPath), { recursive: true });
+  const existing = readWatermark(wmPath);
+  fs.writeFileSync(
+    wmPath,
+    JSON.stringify({
+      conversation_id: convId,
+      last_line_number: lineNum,
+      agent_id: agentId != null ? agentId : existing.agent_id || "",
+      updated_at: new Date().toISOString(),
+    })
+  );
+}
+
+// --- MCP JSON-RPC client (Streamable HTTP with session init) ---
+
+/**
+ * Low-level HTTP POST to the MCP endpoint.
+ * Returns { body: <parsed JSON>, headers: <response headers> }.
+ */
+function mcpPost(jsonBody) {
+  const body = JSON.stringify(jsonBody);
+  return new Promise((resolve, reject) => {
+    const url = new URL(MEKO_MCP_URL);
+    const transport = url.protocol === "https:" ? https : http;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      "Content-Length": Buffer.byteLength(body),
+    };
+    if (MEKO_API_KEY) {
+      headers["API_KEY"] = MEKO_API_KEY;
+    }
+    if (mcpSessionId) {
+      headers["Mcp-Session-Id"] = mcpSessionId;
+    }
+
+    const req = transport.request(
+      {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname + url.search,
+        method: "POST",
+        headers,
+        timeout: MEKO_API_TIMEOUT,
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          inflightRequests.delete(req);
+          // Notifications return 202/204 with no body — that's OK
+          if (!data.trim()) {
+            resolve({ body: null, headers: res.headers });
+            return;
+          }
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.error) {
+              reject(new Error(JSON.stringify(parsed.error)));
+            } else {
+              resolve({ body: parsed, headers: res.headers });
+            }
+          } catch {
+            reject(new Error(`Invalid JSON response: ${data.slice(0, 200)}`));
+          }
+        });
+      }
+    );
+
+    inflightRequests.add(req);
+    req.on("error", (err) => {
+      inflightRequests.delete(req);
+      reject(err);
+    });
+    req.on("timeout", () => {
+      inflightRequests.delete(req);
+      req.destroy();
+      reject(new Error("MCP request timed out"));
+    });
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Abort all pending MCP requests. Used by the preload timeout path so the
+ * SessionStart hook can return promptly instead of waiting for a slow server
+ * to finish responding.
+ */
+function abortInflightRequests() {
+  for (const req of inflightRequests) {
+    try {
+      req.destroy();
+    } catch {
+      // no-op
+    }
+  }
+  inflightRequests.clear();
+}
+
+/**
+ * Initialize MCP session — required before any tools/call.
+ * Sends initialize + notifications/initialized per Streamable HTTP spec.
+ */
+async function mcpInitialize() {
+  mcpRequestId++;
+  const initResult = await mcpPost({
+    jsonrpc: "2.0",
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-03-26",
+      capabilities: {},
+      clientInfo: { name: "meko-capture", version: "1.0.0" },
+    },
+    id: mcpRequestId,
+  });
+
+  // Extract session ID from response header
+  const sid =
+    initResult.headers["mcp-session-id"] ||
+    initResult.headers["Mcp-Session-Id"];
+  if (sid) {
+    mcpSessionId = sid;
+  }
+
+  // Send initialized notification (fire-and-forget, no id)
+  await mcpPost({
+    jsonrpc: "2.0",
+    method: "notifications/initialized",
+    params: {},
+  });
+}
+
+async function mcpCall(toolName, args) {
+  mcpRequestId++;
+  const result = await mcpPost({
+    jsonrpc: "2.0",
+    method: "tools/call",
+    params: { name: toolName, arguments: args },
+    id: mcpRequestId,
+  });
+  return result.body;
+}
+
+function extractToolResult(response) {
+  try {
+    const text = response.result.content[0].text;
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover the user's agent_id namespace from existing Mem0 collections.
+ *
+ * Mirrors the protocol in skills/skills/meko-mcp-tools/SKILL.md lines 41-49:
+ * call `db_summarize_database`, scan for `<agent>_mem0_collection` tables,
+ * pick the one with the highest `row_count`. Falls back to "agent" when the
+ * user has no prior memories. Never returns null — always returns a usable
+ * string.
+ *
+ * Cached in the watermark file so subsequent SessionStart hooks skip the
+ * `db_summarize_database` round-trip.
+ */
+async function discoverAgentId() {
+  const response = await mcpCall("db_summarize_database", {
+    scope: "read",
+    conversation_id: "00000000-0000-0000-0000-000000000000",
+  });
+  const result = extractToolResult(response);
+  if (!result) return "agent";
+
+  // The tool may return tables in several shapes depending on server version.
+  // Defensive: look for any array of { name, row_count } under common keys.
+  const tables = []
+    .concat(result.tables || [])
+    .concat(result.schemas?.flatMap?.((s) => s.tables || []) || []);
+  if (!Array.isArray(tables) || tables.length === 0) return "agent";
+
+  let best = { agent: "", rows: -1 };
+  for (const t of tables) {
+    const name = t.name || t.table_name || "";
+    const rows = Number(t.row_count ?? t.rows ?? 0);
+    const m = /^(.+)_mem0_collection$/.exec(name);
+    if (!m) continue;
+    if (rows > best.rows) {
+      best = { agent: m[1], rows };
+    }
+  }
+  return best.rows > 0 ? best.agent : "agent";
+}
+
+/**
+ * Fetch recent memories for the chosen agent_id namespace.
+ *
+ * Returns an array of short summaries (one per memory), truncated to a global
+ * byte budget so the SessionStart `additionalContext` payload stays compact.
+ * On any error the caller falls back to an empty list — memory preload is a
+ * best-effort enrichment, not a correctness requirement.
+ */
+async function fetchRecentMemories(agentId, { limit = 10, budget = 2000 } = {}) {
+  const response = await mcpCall("memory_get_all", {
+    scope: "read",
+    agent_id: agentId,
+    conversation_id: "00000000-0000-0000-0000-000000000000",
+    limit,
+  });
+  const result = extractToolResult(response);
+  if (!result) return [];
+
+  const entries = Array.isArray(result) ? result : result.memories || result.results || [];
+  const summaries = [];
+  let used = 0;
+  for (const entry of entries) {
+    const text = entry.memory || entry.text || entry.content || "";
+    if (!text) continue;
+    const line = `- ${String(text).replace(/\s+/g, " ").trim()}`;
+    if (used + line.length + 1 > budget) break;
+    summaries.push(line);
+    used += line.length + 1;
+  }
+  return summaries;
+}
+
+async function createConversation(sessionId) {
+  const response = await mcpCall("conversation_create", {
+    scope: "write",
+    agent_id: MEKO_AGENT_ID,
+    title: "Claude Code session (auto-captured)",
+    session_id: sessionId,
+  });
+  const result = extractToolResult(response);
+  return result && result.id ? result.id : null;
+}
+
+async function addMessage(convId, exchange) {
+  const seed = `${convId}:${exchange.user_uuid}`;
+  await mcpCall("conversation_add_message", {
+    scope: "write",
+    conversation_id: convId,
+    agent_id: MEKO_AGENT_ID,
+    input: exchange.input,
+    output: exchange.output,
+    reasoning: exchange.reasoning,
+    seed: seed,
+  });
+}
+
+// --- Hook output ---
+
+function hookEventName(hookType) {
+  switch (hookType) {
+    case "session-start": return "SessionStart";
+    case "pre-compact": return "PreCompact";
+    default: return "SessionEnd";
+  }
+}
+
+function hookOutput(additionalContext) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: hookEventName(process.argv[2]),
+      additionalContext: additionalContext || "",
+    },
+  });
+}
+
+// --- Main ---
+
+// --- SessionStart: create conversation + watermark deterministically ---
+
+function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
+  try {
+    const projectDir = path.dirname(transcriptPath);
+    const files = fs.readdirSync(projectDir).filter((f) => f.endsWith(".jsonl"));
+    let best = null;
+    for (const f of files) {
+      const sid = path.basename(f, ".jsonl");
+      if (sid === currentSessionId) continue;
+      const wmPath = path.join(WATERMARK_DIR, `${sid}.watermark.json`);
+      if (!fs.existsSync(wmPath)) continue;
+      const wm = readWatermark(wmPath);
+      if (!wm.conversation_id) continue;
+      const ts = wm.updated_at || "";
+      if (!best || ts > best.updated_at) {
+        best = {
+          sessionId: sid,
+          conversation_id: wm.conversation_id,
+          agent_id: wm.agent_id || "",
+          updated_at: ts,
+        };
+      }
+    }
+    return best;
+  } catch (err) {
+    process.stderr.write(`[meko-capture] findMostRecentProjectWatermark failed: ${err.message}\n`);
+    return null;
+  }
+}
+
+function buildSessionStartContext(convId, sessionId, agentId, memories, opts) {
+  const resolvedAgentId = agentId || "claude_code";
+  const resumed = Boolean(opts && opts.resumed);
+  const opening = resumed
+    ? `Resuming Meko conversation **${convId}** from a prior Claude Code session. The watermark file is written — PreCompact and SessionEnd hooks will append this session's new exchanges to the same conversation.`
+    : `Meko conversation **${convId}** was created automatically by the SessionStart hook. The watermark file is written — PreCompact and SessionEnd hooks will capture this session's transcript verbatim.`;
+  const memoryBlock =
+    Array.isArray(memories) && memories.length > 0
+      ? `
+
+### Memories from prior sessions
+
+These facts were preloaded for you — inspect them before acting so you don't re-ask questions the user has already answered:
+
+${memories.join("\n")}`
+      : "";
+
+  return `## Meko Session Active
+
+${opening}
+
+### What you MUST do with Meko tools
+
+- **agent_id**: use "${resolvedAgentId}" (discovered from the user's existing namespace — DO NOT substitute "claude_code" just because you're running in Claude Code; see the meko-mcp-tools skill for why).
+- **conversation_id**: Use "${convId}" for all MCP tool calls that accept it
+- **scope**: Only "read", "write", or "admin"
+
+### Proactive storage (do NOT wait to be asked)
+
+- User shares personal info, preferences, or role → call memory_add immediately
+- User shares org conventions or team standards → call memory_add immediately
+- User asks "what do you know about X?" → call memory_search first
+- User provides structured/tabular data → call db_run_write_query (CREATE TABLE + INSERT)
+
+### Before destructive actions
+
+Before any action that deletes, overwrites, or restructures user content (Write-overwrite, large Edit deletions, rm, git reset --hard, destructive SQL), call memory_search for relevant feedback and confirm with the user if any prior guidance applies.
+
+### Use Meko, not local storage
+
+When Meko MCP tools are available, ALWAYS use them instead of local file-based memory (e.g., writing to ~/.claude/projects/.../memory/). If a Meko tool call fails, fall back to local storage and tell the user.${memoryBlock}`;
+}
+
+function buildSessionStartFallbackContext() {
+  return `## Meko Memory Instructions
+
+The SessionStart hook could not reach the Meko MCP server to create a conversation. Automatic capture may not work for this session.
+
+### What you should still do
+
+- **Use Meko MCP tools** for memory_add, memory_search, etc. when available
+- **agent_id**: ALWAYS use "claude_code" (underscore, NEVER hyphens)
+- **conversation_id**: Use nil UUID "00000000-0000-0000-0000-000000000000" as placeholder
+- **scope**: Only "read", "write", or "admin"
+
+### Proactive storage (do NOT wait to be asked)
+
+- User shares personal info, preferences, or role → call memory_add immediately
+- User shares org conventions or team standards → call memory_add immediately
+- User asks "what do you know about X?" → call memory_search first
+
+### Use Meko, not local storage
+
+When Meko MCP tools are available, ALWAYS use them instead of local file-based memory. If a Meko tool call fails, fall back to local storage and tell the user.`;
+}
+
+/**
+ * Race a promise against a timeout; on timeout resolve to the fallback value.
+ * Memory preload is best-effort — if it stalls, the SessionStart hook must
+ * still deliver the conversation + instructions under the 15 s harness budget.
+ */
+function withTimeout(promise, ms, fallback, { onTimeout } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        if (typeof onTimeout === "function") {
+          try {
+            onTimeout();
+          } catch {
+            // no-op
+          }
+        }
+        resolve(fallback);
+      }
+    }, ms);
+    promise
+      .then((value) => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(value);
+        }
+      })
+      .catch(() => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(fallback);
+        }
+      });
+  });
+}
+
+async function handleSessionStart(hookInput) {
+  const transcriptPath =
+    hookInput.transcript_path ||
+    (hookInput.hookSpecificInput || {}).transcript_path;
+
+  const sessionId = transcriptPath
+    ? path.basename(transcriptPath, ".jsonl")
+    : null;
+
+  const source = hookInput.source || "";
+
+  // Check if watermark already exists (same session ID re-fires SessionStart, e.g. /clear, /compact)
+  if (sessionId) {
+    const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
+    const existing = readWatermark(wmPath);
+    if (existing.conversation_id) {
+      process.stderr.write(`[meko-capture] Session ${sessionId}: reusing existing conversation ${existing.conversation_id}\n`);
+      // Reuse cached agent_id + skip preload on resume (we don't know what's
+      // already in context). The skill still has the discovery protocol as a
+      // safety net.
+      process.stdout.write(
+        hookOutput(
+          buildSessionStartContext(
+            existing.conversation_id,
+            sessionId,
+            existing.agent_id || "",
+            null,
+          ),
+        ),
+      );
+      return;
+    }
+  }
+
+  // Resume: Claude Code created a new session ID for a resumed thread. Find the most recent
+  // prior watermark for this project and reuse its conversation_id so continuity is preserved.
+  // Initialize last_line_number to the current line count so the copied history (which Claude
+  // Code replays into the new JSONL) is not re-ingested.
+  if (source === "resume" && transcriptPath && sessionId) {
+    const prior = findMostRecentProjectWatermark(transcriptPath, sessionId);
+    if (prior && prior.conversation_id) {
+      const currentLineCount = fs.existsSync(transcriptPath) ? countLines(transcriptPath) : 0;
+      const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
+      writeWatermark(wmPath, prior.conversation_id, currentLineCount);
+      process.stderr.write(`[meko-capture] Session ${sessionId}: resuming conversation ${prior.conversation_id} from ${prior.sessionId}, skipping ${currentLineCount} copied lines\n`);
+      process.stdout.write(
+        hookOutput(
+          buildSessionStartContext(
+            prior.conversation_id,
+            sessionId,
+            prior.agent_id || "",
+            null,
+            { resumed: true },
+          ),
+        ),
+      );
+      return;
+    }
+    process.stderr.write(`[meko-capture] Session ${sessionId}: source=resume but no prior project watermark found; creating new conversation\n`);
+  }
+
+  // Create conversation via MCP
+  let convId = null;
+  try {
+    await mcpInitialize();
+    convId = await createConversation(sessionId || "unknown");
+  } catch (err) {
+    process.stderr.write(`[meko-capture] SessionStart: MCP unavailable (${err.message}). Falling back to agent-driven setup.\n`);
+    process.stdout.write(hookOutput(buildSessionStartFallbackContext()));
+    return;
+  }
+
+  if (!convId) {
+    process.stderr.write("[meko-capture] SessionStart: conversation_create returned no ID.\n");
+    process.stdout.write(hookOutput(buildSessionStartFallbackContext()));
+    return;
+  }
+
+  // Discover agent_id + preload memories with a combined 4s budget (SessionStart
+  // timeout is 15s). Both are enrichment — on timeout/failure we still deliver
+  // the core SessionStart context with the MEKO_AGENT_ID default.
+  const PRELOAD_BUDGET_MS = 4000;
+  const preloadResult = await withTimeout(
+    (async () => {
+      const agentId = await discoverAgentId();
+      const memories = await fetchRecentMemories(agentId);
+      return { agentId, memories };
+    })(),
+    PRELOAD_BUDGET_MS,
+    { agentId: MEKO_AGENT_ID, memories: [] },
+    { onTimeout: abortInflightRequests },
+  );
+
+  // Write watermark (now cachinG agent_id too)
+  if (sessionId) {
+    const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
+    writeWatermark(wmPath, convId, 0, preloadResult.agentId);
+    process.stderr.write(
+      `[meko-capture] SessionStart: created conversation ${convId}, agent_id=${preloadResult.agentId}, preloaded ${preloadResult.memories.length} memories, watermark at ${wmPath}\n`,
+    );
+  }
+
+  process.stdout.write(
+    hookOutput(
+      buildSessionStartContext(
+        convId,
+        sessionId,
+        preloadResult.agentId,
+        preloadResult.memories,
+      ),
+    ),
+  );
+}
+
+// --- Main ---
+
+async function main() {
+  const hookType = process.argv[2];
+  if (!hookType || !["session-start", "pre-compact", "session-end", "checkpoint"].includes(hookType)) {
+    process.stderr.write("Usage: capture.js <session-start|pre-compact|session-end|checkpoint>\n");
+    process.exit(1);
+  }
+
+  // Read hook input from stdin
+  let hookInput;
+  try {
+    const stdin = fs.readFileSync(0, "utf-8");
+    hookInput = JSON.parse(stdin);
+  } catch (err) {
+    process.stderr.write(`[meko-capture] Failed to parse hook input from stdin: ${err.message}\n`);
+    process.stdout.write(hookOutput(""));
+    return;
+  }
+
+  // SessionStart: create conversation + watermark, output context
+  if (hookType === "session-start") {
+    await handleSessionStart(hookInput);
+    return;
+  }
+
+  // PreCompact / SessionEnd: capture transcript exchanges
+  const transcriptPath =
+    hookInput.transcript_path ||
+    (hookInput.hookSpecificInput || {}).transcript_path;
+
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    process.stdout.write(hookOutput(""));
+    return;
+  }
+
+  const sessionId = path.basename(transcriptPath, ".jsonl");
+  const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
+  const watermark = readWatermark(wmPath);
+  let convId = watermark.conversation_id || "";
+  const lastLine = watermark.last_line_number || 0;
+  const currentLines = countLines(transcriptPath);
+
+  // Nothing new
+  if (currentLines <= lastLine) {
+    process.stdout.write(hookOutput(""));
+    return;
+  }
+
+  // Initialize MCP session
+  try {
+    await mcpInitialize();
+  } catch (err) {
+    process.stderr.write(`[meko-capture] Failed to initialize MCP session: ${err.message}\n`);
+    process.stdout.write(hookOutput(""));
+    return;
+  }
+
+  // Only SessionStart creates conversations. All other modes require
+  // an existing watermark. Skip gracefully if missing.
+  if (!convId) {
+    process.stderr.write(
+      `[meko-capture] ${hookType}: No conversation in watermark for session ${sessionId}. ` +
+      `SessionStart hook may not have run yet.\n`
+    );
+    process.stdout.write(hookOutput(""));
+    return;
+  }
+
+  // Extract and send exchanges
+  const exchanges = extractExchanges(transcriptPath, lastLine);
+  let captured = 0;
+
+  for (const exchange of exchanges) {
+    try {
+      await addMessage(convId, exchange);
+      captured++;
+    } catch (err) {
+      process.stderr.write(`[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`);
+    }
+  }
+
+  // Update watermark
+  writeWatermark(wmPath, convId, currentLines);
+
+  // Output
+  const context =
+    hookType === "pre-compact"
+      ? `Pre-compact: captured ${captured} exchanges to Meko conversation ${convId}`
+      : "";
+  process.stdout.write(hookOutput(context));
+}
+
+main().catch((err) => {
+  process.stderr.write(`[meko-capture] Fatal error: ${err.message}\n`);
+  process.stdout.write(hookOutput(""));
+});