@yugabytedb/meko-mcp 2.1.0 → 2.2.0

package/assets/hooks-handlers/lib/kiro-handler.js

@@ -0,0 +1,738 @@
+#!/usr/bin/env node
+/**
+ * Durable Kiro hook adapter.
+ *
+ * Kiro 2.x emits inline custom-agent events (`agentSpawn`,
+ * `userPromptSubmit`, `stop`). Kiro CLI 3.x and IDE 1.x emit standalone
+ * lifecycle events (`SessionStart`, `UserPromptSubmit`, `Stop`). Both formats
+ * arrive here and are normalized into one append-only Claude-shaped JSONL
+ * journal. capture.js then owns conversation creation, acknowledgement,
+ * cursor advancement, retry, and recovery exactly as it does for other
+ * clients.
+ *
+ * Stop is intentionally silent and non-blocking: the final response is fsynced
+ * locally, then a detached Capture v2 drain is launched. The recovery timer
+ * retries anything the detached drain cannot deliver.
+ */
+
+"use strict";
+
+const childProcess = require("child_process");
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_ENV_PATH = path.join(__dirname, "..", "kiro-hook-env.json");
+const ACTIVE_MARKER = "MEKO_CAPTURE_SESSION_STARTED";
+
+function loadHookEnvironment(filePath) {
+  const target = filePath || process.env.MEKO_KIRO_ENV_FILE || DEFAULT_ENV_PATH;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
+    for (const key of [
+      "MEKO_MCP_URL",
+      "MEKO_API_KEY",
+      "MEKO_AGENT_ID",
+      "MEKO_WATERMARK_DIR",
+      "MEKO_DATAPACK_ID",
+      "MEKO_DATAPACK_NAME",
+    ]) {
+      if (typeof parsed[key] === "string" && parsed[key] !== "") {
+        process.env[key] = parsed[key];
+      } else if (key === "MEKO_API_KEY" && parsed[key] === "") {
+        delete process.env[key];
+      }
+    }
+  } catch (err) {
+    if (!err || err.code !== "ENOENT") {
+      process.stderr.write(`[meko-kiro] Could not read hook environment: ${err.message}\n`);
+    }
+  }
+  process.env.MEKO_HOOK_CLIENT = "kiro";
+  return target;
+}
+
+loadHookEnvironment();
+
+const captureState = require("./capture-state");
+const {
+  deriveAgentId,
+  INTERRUPTED_ASSISTANT_OUTPUT,
+} = require("./capture");
+
+const EVENT_DIR = path.join(captureState.watermarkDir(), "kiro-events");
+const LOCK_RETRIES = 100;
+const LOCK_RETRY_MS = 10;
+const CORRELATION_MAX_IDLE_MS = 2 * 60 * 60 * 1000;
+const CORRELATION_START_DEDUP_MS = 30 * 1000;
+const DEFAULT_CONVERSATION_BIND_TIMEOUT_MS = 4_000;
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return "";
+}
+
+function normalizeEventName(value) {
+  const compact = String(value || "").replace(/[^A-Za-z]/g, "").toLowerCase();
+  if (compact === "agentspawn" || compact === "sessionstart") return "session-start";
+  if (compact === "userpromptsubmit" || compact === "promptsubmit") return "user-prompt";
+  if (compact === "stop" || compact === "agentstop") return "stop";
+  return "";
+}
+
+function safeSessionId(value) {
+  const raw = String(value || "").trim();
+  if (/^[A-Za-z0-9_.-]+$/.test(raw)) return raw;
+  const base = raw.replace(/[^A-Za-z0-9_.-]+/g, "_").replace(/^_+|_+$/g, "") || "kiro";
+  return `${base.slice(0, 80)}-${sha(raw).slice(0, 12)}`;
+}
+
+function sha(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex");
+}
+
+function normalizeHookInput(rawInput, explicitEvent, options = {}) {
+  const raw = rawInput && typeof rawInput === "object" ? rawInput : {};
+  const nested = raw.hookSpecificInput && typeof raw.hookSpecificInput === "object"
+    ? raw.hookSpecificInput
+    : {};
+  const env = options.env || process.env;
+  const event = normalizeEventName(
+    explicitEvent || raw.hook_event_name || raw.hookEventName || raw.event || raw.trigger,
+  );
+  const cwd = firstString(
+    raw.cwd,
+    raw.workspace_path,
+    raw.workspacePath,
+    raw.project_root,
+    nested.cwd,
+    nested.workspace_path,
+    nested.workspacePath,
+    nested.project_root,
+    options.cwd,
+    process.cwd(),
+  );
+  const suppliedSessionId = firstString(
+    raw.session_id,
+    raw.sessionId,
+    raw.conversation_id,
+    raw.conversationId,
+    nested.session_id,
+    nested.sessionId,
+  );
+  const hostPidRaw =
+    raw.host_pid ?? raw.hostPid ?? raw.process_id ?? raw.processId ?? raw.pid ??
+    nested.host_pid ?? nested.hostPid ?? nested.process_id ?? nested.processId ?? nested.pid ??
+    env.KIRO_HOST_PID ?? options.parentPid ?? process.ppid;
+  const hostPid = Number.isInteger(Number(hostPidRaw)) && Number(hostPidRaw) > 0
+    ? Number(hostPidRaw)
+    : 0;
+  const fallbackId = `kiro-pid-${hostPid || "unknown"}-${sha(cwd).slice(0, 12)}`;
+  const sessionId = safeSessionId(suppliedSessionId || fallbackId);
+  const userPrompt = firstString(
+    raw.user_prompt,
+    raw.userPrompt,
+    raw.prompt,
+    nested.user_prompt,
+    nested.userPrompt,
+    nested.prompt,
+    env.USER_PROMPT,
+  );
+  const assistantResponse = firstString(
+    raw.assistant_response,
+    raw.assistantResponse,
+    raw.response,
+    raw.output,
+    nested.assistant_response,
+    nested.assistantResponse,
+    nested.response,
+    env.ASSISTANT_RESPONSE,
+  );
+  const eventId = firstString(
+    raw.event_id,
+    raw.eventId,
+    raw.request_id,
+    raw.requestId,
+    nested.event_id,
+    nested.eventId,
+  );
+  return {
+    event,
+    rawEvent: firstString(explicitEvent, raw.hook_event_name, raw.event, raw.trigger),
+    sessionId,
+    suppliedSessionId: Boolean(suppliedSessionId),
+    suppliedSessionValue: suppliedSessionId ? safeSessionId(suppliedSessionId) : "",
+    fallbackSessionId: fallbackId,
+    cwd,
+    hostPid,
+    userPrompt,
+    assistantResponse,
+    eventId,
+    timestamp: firstString(raw.timestamp, nested.timestamp) || new Date().toISOString(),
+  };
+}
+
+function eventPaths(sessionId) {
+  return {
+    journal: path.join(EVENT_DIR, `${sessionId}.jsonl`),
+    state: path.join(EVENT_DIR, `${sessionId}.state.json`),
+    lock: path.join(EVENT_DIR, `${sessionId}.lock`),
+  };
+}
+
+function correlationPaths(fallbackSessionId) {
+  const key = sha(fallbackSessionId).slice(0, 24);
+  return {
+    state: path.join(EVENT_DIR, `kiro-correlation-${key}.json`),
+    lock: path.join(EVENT_DIR, `kiro-correlation-${key}.lock`),
+  };
+}
+
+function ensureEventDir() {
+  fs.mkdirSync(EVENT_DIR, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(EVENT_DIR, 0o700); } catch { /* best effort */ }
+}
+
+function sleepSync(ms) {
+  const cell = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(cell, 0, 0, ms);
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireEventLock(lockPath) {
+  ensureEventDir();
+  for (let attempt = 0; attempt < LOCK_RETRIES; attempt++) {
+    try {
+      const fd = fs.openSync(lockPath, "wx", 0o600);
+      try {
+        fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, created_at: Date.now() }));
+      } finally {
+        fs.closeSync(fd);
+      }
+      return true;
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") throw err;
+      let existing = null;
+      try { existing = JSON.parse(fs.readFileSync(lockPath, "utf8")); } catch { /* reclaim */ }
+      if (!existing || !pidAlive(Number(existing.pid))) {
+        try { fs.unlinkSync(lockPath); } catch { /* another process won */ }
+        continue;
+      }
+      sleepSync(LOCK_RETRY_MS);
+    }
+  }
+  throw new Error(`timed out acquiring event lock ${lockPath}`);
+}
+
+function releaseEventLock(lockPath) {
+  try {
+    const current = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    if (Number(current.pid) === process.pid) fs.unlinkSync(lockPath);
+  } catch { /* already gone */ }
+}
+
+function emptyEventState(sessionId) {
+  return {
+    schema_version: 1,
+    session_id: sessionId,
+    turn_index: 0,
+    pending: null,
+    updated_at: new Date().toISOString(),
+  };
+}
+
+function rebuildEventState(journalPath, sessionId) {
+  const rebuilt = emptyEventState(sessionId);
+  let contents;
+  try {
+    contents = fs.readFileSync(journalPath, "utf8");
+  } catch {
+    return rebuilt;
+  }
+
+  for (const line of contents.split("\n")) {
+    if (!line.trim()) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      // A damaged record must not make every later fsynced turn invisible.
+      // appendJournal repairs torn tails before adding new records; skipping
+      // here also lets recovery make progress after unrelated disk corruption.
+      continue;
+    }
+    if (!record || record.session_id !== sessionId) continue;
+    if (record.type === "user") {
+      const content = record.message && record.message.content;
+      const text = Array.isArray(content) && content[0] && typeof content[0].text === "string"
+        ? content[0].text
+        : "";
+      rebuilt.turn_index += 1;
+      rebuilt.pending = {
+        prompt_hash: sha(text),
+        user_uuid: String(record.uuid || ""),
+        turn_index: rebuilt.turn_index,
+      };
+    } else if (record.type === "assistant" && rebuilt.pending) {
+      rebuilt.pending = null;
+    }
+  }
+  return rebuilt;
+}
+
+function readEventState(statePath, journalPath, sessionId) {
+  let persisted = null;
+  try {
+    const value = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    if (value && value.schema_version === 1 && value.session_id === sessionId) {
+      persisted = value;
+    }
+  } catch { /* fresh or corrupt rebuildable sidecar */ }
+
+  // The fsynced append-only journal is authoritative. Re-derive pairing on
+  // every hook so either crash window (journal append before sidecar commit)
+  // heals without duplicating or dropping a turn.
+  const rebuilt = rebuildEventState(journalPath, sessionId);
+  return {
+    ...(persisted || emptyEventState(sessionId)),
+    turn_index: rebuilt.turn_index,
+    pending: rebuilt.pending,
+  };
+}
+
+function atomicWriteJson(filePath, value) {
+  ensureEventDir();
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  const fd = fs.openSync(tmp, "w", 0o600);
+  try {
+    fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, filePath);
+  try { fs.chmodSync(filePath, 0o600); } catch { /* best effort */ }
+}
+
+function appendJournal(journalPath, record) {
+  ensureEventDir();
+  try {
+    const contents = fs.readFileSync(journalPath);
+    if (contents.length > 0 && contents[contents.length - 1] !== 0x0a) {
+      const lastNewline = contents.lastIndexOf(0x0a);
+      fs.truncateSync(journalPath, lastNewline < 0 ? 0 : lastNewline + 1);
+    }
+  } catch (err) {
+    if (!err || err.code !== "ENOENT") throw err;
+  }
+
+  const data = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+  const fd = fs.openSync(journalPath, "a", 0o600);
+  try {
+    let offset = 0;
+    while (offset < data.length) {
+      const written = fs.writeSync(fd, data, offset, data.length - offset, null);
+      if (!Number.isInteger(written) || written <= 0) {
+        throw new Error(`could not append complete Kiro journal record to ${journalPath}`);
+      }
+      offset += written;
+    }
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try { fs.chmodSync(journalPath, 0o600); } catch { /* best effort */ }
+}
+
+function resolveCorrelatedSession(event, options = {}) {
+  const fallbackSessionId = event.fallbackSessionId || event.sessionId;
+  const paths = correlationPaths(fallbackSessionId);
+  const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+  const isHostPidAlive = options.isHostPidAlive || pidAlive;
+  acquireEventLock(paths.lock);
+  try {
+    let existing = null;
+    try {
+      const value = JSON.parse(fs.readFileSync(paths.state, "utf8"));
+      if (value?.schema_version === 1 && value?.fallback_session_id === fallbackSessionId) {
+        existing = value;
+      }
+    } catch { /* first event or rebuildable correlation sidecar */ }
+
+    const supplied = event.suppliedSessionValue || "";
+    const previous = existing;
+    if (existing) {
+      const updatedAtMs = Date.parse(existing.updated_at || "");
+      const ageMs = Number.isFinite(updatedAtMs) ? Math.max(0, nowMs - updatedAtMs) : Infinity;
+      const sameInitialPrompt = Boolean(
+        event.userPrompt &&
+        existing.last_prompt_hash &&
+        existing.last_prompt_hash === sha(event.userPrompt),
+      );
+      const duplicateInitialStart = Boolean(
+        event.event === "session-start" &&
+        ageMs <= CORRELATION_START_DEDUP_MS &&
+        (
+          existing.last_event === "session-start" ||
+          (existing.last_event === "user-prompt" && sameInitialPrompt)
+        ),
+      );
+      const newFallbackLifecycle = Boolean(
+        !supplied && event.event === "session-start" && !duplicateInitialStart,
+      );
+      const hostStillOwnsCorrelation = Boolean(
+        Number(existing.host_pid) === event.hostPid && isHostPidAlive(Number(existing.host_pid)),
+      );
+      if (
+        !hostStillOwnsCorrelation ||
+        ageMs > CORRELATION_MAX_IDLE_MS ||
+        newFallbackLifecycle
+      ) {
+        existing = null;
+      }
+    }
+
+    let canonicalSessionId;
+    if (supplied && existing?.supplied_session_id === supplied) {
+      canonicalSessionId = existing.canonical_session_id;
+    } else if (supplied && existing && !existing.supplied_session_id) {
+      // The standalone format arrived first without a session ID. Bind the
+      // inline format to that already-created journal so delivery order cannot
+      // create a second conversation.
+      canonicalSessionId = existing.canonical_session_id;
+    } else if (supplied) {
+      // A different real Kiro session on the same long-lived host starts a new
+      // correlation rather than inheriting the previous PID+cwd session.
+      canonicalSessionId = supplied;
+    } else if (existing?.canonical_session_id) {
+      canonicalSessionId = existing.canonical_session_id;
+    } else if (previous) {
+      // A dead host, idle record, or new fallback-only SessionStart must not
+      // append to the prior journal. The sidecar binds concurrent delivery to
+      // this generation after the first process writes it.
+      canonicalSessionId = safeSessionId(
+        `${fallbackSessionId}-g-${sha(`${previous.canonical_session_id || ""}:${nowMs}:${event.timestamp}:${event.eventId || ""}`).slice(0, 12)}`,
+      );
+    } else {
+      canonicalSessionId = fallbackSessionId;
+    }
+
+    atomicWriteJson(paths.state, {
+      schema_version: 1,
+      fallback_session_id: fallbackSessionId,
+      canonical_session_id: canonicalSessionId,
+      supplied_session_id: supplied || existing?.supplied_session_id || null,
+      host_pid: event.hostPid || null,
+      last_event: event.event,
+      last_prompt_hash: event.userPrompt
+        ? sha(event.userPrompt)
+        : existing?.last_prompt_hash || null,
+      updated_at: new Date(nowMs).toISOString(),
+    });
+    return { ...event, sessionId: canonicalSessionId };
+  } finally {
+    releaseEventLock(paths.lock);
+  }
+}
+
+function journalEmpty(journalPath) {
+  try { return fs.statSync(journalPath).size === 0; } catch { return true; }
+}
+
+function userRecord(event, turnIndex, userUuid) {
+  return {
+    type: "user",
+    uuid: userUuid,
+    session_id: event.sessionId,
+    cwd: event.cwd,
+    timestamp: event.timestamp,
+    message: { role: "user", content: [{ type: "text", text: event.userPrompt }] },
+    kiro: { event_id: event.eventId || null, source_event: event.rawEvent || event.event },
+  };
+}
+
+function assistantRecord(event, userUuid, text, interrupted = false) {
+  return {
+    type: "assistant",
+    uuid: `kiro-assistant-${sha(`${event.sessionId}:${userUuid}:${text}`).slice(0, 24)}`,
+    session_id: event.sessionId,
+    cwd: event.cwd,
+    timestamp: event.timestamp,
+    message: { role: "assistant", content: [{ type: "text", text }] },
+    kiro: {
+      event_id: event.eventId || null,
+      source_event: event.rawEvent || event.event,
+      interrupted,
+    },
+  };
+}
+
+function journalEvent(event) {
+  const paths = eventPaths(event.sessionId);
+  acquireEventLock(paths.lock);
+  try {
+    let sessionCreated = false;
+    if (journalEmpty(paths.journal)) {
+      appendJournal(paths.journal, {
+        type: "kiro_session",
+        session_id: event.sessionId,
+        cwd: event.cwd,
+        host_pid: event.hostPid || null,
+        timestamp: event.timestamp,
+        client: "kiro",
+      });
+      sessionCreated = true;
+    }
+    const state = readEventState(paths.state, paths.journal, event.sessionId);
+
+    let appended = false;
+    let interrupted = false;
+    if ((event.event === "session-start" || event.event === "user-prompt") && event.userPrompt) {
+      const promptHash = sha(event.userPrompt);
+      if (!(state.pending && state.pending.prompt_hash === promptHash)) {
+        if (state.pending) {
+          appendJournal(
+            paths.journal,
+            assistantRecord(event, state.pending.user_uuid, INTERRUPTED_ASSISTANT_OUTPUT, true),
+          );
+          interrupted = true;
+        }
+        state.turn_index += 1;
+        const userUuid = `kiro-user-${sha(`${event.sessionId}:${state.turn_index}:${event.userPrompt}`).slice(0, 24)}`;
+        appendJournal(paths.journal, userRecord(event, state.turn_index, userUuid));
+        state.pending = {
+          prompt_hash: promptHash,
+          user_uuid: userUuid,
+          turn_index: state.turn_index,
+        };
+        appended = true;
+      }
+    } else if (event.event === "stop" && event.assistantResponse && state.pending) {
+      appendJournal(
+        paths.journal,
+        assistantRecord(event, state.pending.user_uuid, event.assistantResponse, false),
+      );
+      state.pending = null;
+      appended = true;
+    }
+    state.updated_at = new Date().toISOString();
+    atomicWriteJson(paths.state, state);
+    return { paths, state, appended, interrupted, sessionCreated };
+  } finally {
+    releaseEventLock(paths.lock);
+  }
+}
+
+function ensureCaptureIntent(event, journalPath) {
+  const agentId = deriveAgentId({
+    client: "kiro",
+    cwd: event.cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+  });
+  const intent = captureState.writeSessionIntent(event.sessionId, {
+    client: "kiro",
+    agent_id: agentId,
+    agent_id_source: (process.env.MEKO_AGENT_ID || "").trim() ? "explicit" : "derived",
+    transcript_path: journalPath,
+    datapack_id: process.env.MEKO_DATAPACK_ID || null,
+    datapack_name: process.env.MEKO_DATAPACK_NAME || null,
+  });
+  return { ...intent, agentId };
+}
+
+function launchCapture(mode, payload) {
+  const captureScript = path.join(__dirname, "capture.js");
+  const child = childProcess.spawn(process.execPath, [captureScript, mode], {
+    detached: true,
+    stdio: ["pipe", "ignore", "ignore"],
+    env: { ...process.env, MEKO_HOOK_CLIENT: "kiro" },
+  });
+  child.stdin.on("error", () => {});
+  child.stdin.end(JSON.stringify(payload));
+  child.unref();
+}
+
+function initializeCapture(mode, payload, timeoutMs) {
+  const captureScript = path.join(__dirname, "capture.js");
+  const parsed = Number(timeoutMs);
+  const timeout = Number.isFinite(parsed)
+    ? Math.max(1, parsed)
+    : DEFAULT_CONVERSATION_BIND_TIMEOUT_MS;
+  const result = childProcess.spawnSync(process.execPath, [captureScript, mode], {
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    timeout,
+    stdio: ["pipe", "ignore", "pipe"],
+    env: { ...process.env, MEKO_HOOK_CLIENT: "kiro" },
+  });
+  if (result.error) {
+    process.stderr.write(`[meko-kiro] Initial conversation bind failed: ${result.error.message}\n`);
+    return false;
+  }
+  if (result.status !== 0) {
+    const detail = String(result.stderr || "").trim().split("\n").at(-1) || `exit ${result.status}`;
+    process.stderr.write(`[meko-kiro] Initial conversation bind failed: ${detail}\n`);
+    return false;
+  }
+  return true;
+}
+
+function launchRecoveryTimer(journalPath) {
+  const timerScript = path.join(__dirname, "checkpoint-timer.js");
+  const child = childProcess.spawn(process.execPath, [timerScript, journalPath], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, MEKO_HOOK_CLIENT: "kiro" },
+  });
+  child.unref();
+}
+
+function checkpointPayload(event, journalPath) {
+  return {
+    session_id: event.sessionId,
+    transcript_path: journalPath,
+    lifecycle: "active",
+  };
+}
+
+function conversationContext(sessionId) {
+  const result = captureState.readState(sessionId);
+  const conversationId = result.ok ? result.state.conversation_id : "";
+  if (typeof conversationId !== "string" || !/^[0-9a-f-]{32,36}$/i.test(conversationId)) {
+    return "";
+  }
+  return (
+    `MEKO_CONVERSATION_ID=${conversationId}\n` +
+    "Use this exact conversation_id for Meko tool calls that accept it.\n"
+  );
+}
+
+function handleNormalizedEvent(event, options = {}) {
+  if (!event.event) return { stdout: "", status: "ignored", event };
+  event = resolveCorrelatedSession(event, options);
+  const journaled = journalEvent(event);
+  const intent = ensureCaptureIntent(event, journaled.paths.journal);
+  if (!intent.ok) {
+    process.stderr.write(`[meko-kiro] Capture intent failed: ${intent.error}\n`);
+    return { stdout: "", status: "intent-failed", event, journaled, intent };
+  }
+
+  const launch = options.launch !== false;
+  const startCapture = options.launchCapture || launchCapture;
+  const bindConversation = options.initializeCapture || initializeCapture;
+  const startRecoveryTimer = options.launchRecoveryTimer || launchRecoveryTimer;
+  if (event.event === "session-start") {
+    if (launch && journaled.sessionCreated) {
+      // Kiro does not consume capture.js SessionStart context. Initialize via
+      // a bounded checkpoint so conversation create + bind completes before
+      // the immediately-following first prompt can invoke tools. Capture v2's
+      // per-session drain lease still serializes all initialization.
+      bindConversation(
+        "checkpoint",
+        checkpointPayload(event, journaled.paths.journal),
+        options.conversationBindTimeoutMs,
+      );
+      startRecoveryTimer(journaled.paths.journal);
+    }
+    const context = conversationContext(event.sessionId);
+    return {
+      stdout:
+        `${ACTIVE_MARKER}\n` +
+        "Meko Capture v2 is active for this Kiro session. Follow the hook-capture path in Meko steering; do not proactively duplicate captured conversational facts.\n" +
+        context,
+      status: "active",
+      event,
+      journaled,
+      intent,
+    };
+  }
+
+  if (event.event === "user-prompt") {
+    if (launch && journaled.sessionCreated) {
+      // A standalone UserPromptSubmit can be the first trusted hook seen (for
+      // example after an upgrade). The journal header is the durable once-per-
+      // session launch claim, so dual-format delivery cannot fan out creators.
+      bindConversation(
+        "checkpoint",
+        checkpointPayload(event, journaled.paths.journal),
+        options.conversationBindTimeoutMs,
+      );
+      startRecoveryTimer(journaled.paths.journal);
+    }
+    let context = conversationContext(event.sessionId);
+    if (launch && !context && !journaled.sessionCreated) {
+      // The prior agentSpawn may have timed out or been delivered concurrently.
+      // Retry through the same leased checkpoint before this prompt can use
+      // tools; recovery remains responsible if the endpoint is unavailable.
+      bindConversation(
+        "checkpoint",
+        checkpointPayload(event, journaled.paths.journal),
+        options.conversationBindTimeoutMs,
+      );
+      context = conversationContext(event.sessionId);
+    }
+    return {
+      stdout: context,
+      status: "journaled",
+      event,
+      journaled,
+      intent,
+    };
+  }
+
+  if (event.event === "stop" && launch && journaled.appended) {
+    startCapture("checkpoint", checkpointPayload(event, journaled.paths.journal));
+  }
+  return { stdout: "", status: "journaled", event, journaled, intent };
+}
+
+function handleHookInput(rawInput, explicitEvent, options = {}) {
+  return handleNormalizedEvent(
+    normalizeHookInput(rawInput, explicitEvent, options),
+    options,
+  );
+}
+
+function main() {
+  let input = {};
+  try {
+    input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+  } catch (err) {
+    process.stderr.write(`[meko-kiro] Invalid hook input: ${err.message}\n`);
+    return;
+  }
+  try {
+    const result = handleHookInput(input, process.argv[2] || "");
+    if (result.stdout) process.stdout.write(result.stdout);
+  } catch (err) {
+    // Hook commands are observability plumbing, not a reason to fail the Kiro
+    // lifecycle event. Keep stdout protocol-clean and leave a concise local
+    // diagnostic while the durable recovery path handles prior records.
+    process.stderr.write(`[meko-kiro] Hook failed: ${err.message}\n`);
+  }
+}
+
+module.exports = {
+  ACTIVE_MARKER,
+  normalizeEventName,
+  normalizeHookInput,
+  safeSessionId,
+  eventPaths,
+  journalEvent,
+  handleNormalizedEvent,
+  handleHookInput,
+  loadHookEnvironment,
+};
+
+if (require.main === module) main();