ultrahope 0.1.3 → 0.1.4

package/dist/git-ultrahope.js

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
 // commands/commit.ts
-import { execSync as execSync2, spawn as spawn2 } from "child_process";
-import { mkdtempSync as mkdtempSync2, readFileSync as readFileSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join5 } from "path";
+import { execSync as execSync2 } from "child_process";
 
 // lib/api-client.ts
 import createClient from "openapi-fetch";
@@ -39,11 +36,33 @@ function log(message, data) {
 // lib/api-client.ts
 var API_BASE_URL = process.env.ULTRAHOPE_API_URL ?? "https://ultrahope.dev";
 var InsufficientBalanceError = class extends Error {
-  constructor(balance) {
+  constructor(balance, plan = "free", hint, actions) {
     super("Token balance exhausted");
     this.balance = balance;
+    this.plan = plan;
+    this.hint = hint;
+    this.actions = actions;
     this.name = "InsufficientBalanceError";
   }
+  formatMessage() {
+    const lines = [];
+    if (this.plan === "pro") {
+      lines.push(
+        "Error: Your usage credit has been exhausted. Purchase additional credits to continue."
+      );
+      if (this.actions?.buyCredits) {
+        lines.push(`  Buy credits: ${this.actions.buyCredits}`);
+      }
+    } else {
+      lines.push(
+        "Error: Your free credit has been exhausted. Upgrade to Pro for unlimited requests with $5 included credit."
+      );
+      if (this.actions?.upgrade) {
+        lines.push(`  Upgrade: ${this.actions.upgrade}`);
+      }
+    }
+    return lines.join("\n");
+  }
 };
 var DailyLimitExceededError = class extends Error {
   constructor(count, limit, resetsAt) {
@@ -110,12 +129,17 @@ function parseSseEvents(buffer) {
   return { events, remainder };
 }
 function handle402Error(error) {
-  const errorBalance = error?.balance;
-  if (typeof errorBalance === "number") {
+  const payload = error;
+  if (typeof payload?.balance === "number") {
     log("generate error (402 insufficient_balance)", error);
-    throw new InsufficientBalanceError(errorBalance);
+    const plan = payload.plan === "pro" || payload.plan === "free" ? payload.plan : "free";
+    throw new InsufficientBalanceError(
+      payload.balance,
+      plan,
+      payload.hint,
+      payload.actions
+    );
   }
-  const payload = error;
   const count = typeof payload?.count === "number" ? payload.count : 0;
   const limit = typeof payload?.limit === "number" ? payload.limit : 0;
   const resetsAt = payload?.resetsAt ?? "";
@@ -238,12 +262,8 @@ function createApiClient(token) {
         throw new UnauthorizedError();
       }
       if (response.status === 402) {
-        const payload = error;
-        const count = typeof payload?.count === "number" ? payload.count : 0;
-        const limit = typeof payload?.limit === "number" ? payload.limit : 0;
-        const resetsAt = payload?.resetsAt ?? "";
         log("command_execution error (402)", error);
-        throw new DailyLimitExceededError(count, limit, resetsAt);
+        handle402Error(error);
       }
       if (!response.ok) {
         const text = await getErrorText(response, error);
@@ -595,7 +615,7 @@ async function showDailyLimitPrompt(info) {
   }
 }
 function promptChoice() {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const fd = openSync("/dev/tty", "r");
     const ttyInput = new tty.ReadStream(fd);
     const rl = readline.createInterface({
@@ -618,17 +638,17 @@ function promptChoice() {
       if (!key && !str) return;
       if (str === "q" || str === "Q" || key?.name === "q" || key?.name === "c" && key.ctrl || key?.name === "escape") {
         cleanup();
-        resolve2("q");
+        resolve3("q");
         return;
       }
       if (str === "1" || key?.name === "1" || key?.sequence === "1") {
         cleanup();
-        resolve2("1");
+        resolve3("1");
         return;
       }
       if (str === "2" || key?.name === "2" || key?.sequence === "2") {
         cleanup();
-        resolve2("2");
+        resolve3("2");
         return;
       }
     };
@@ -645,7 +665,7 @@ function handleRetryLater() {
   );
   console.log(`  ${ui.link("ultrahope jj describe")}`);
   console.log("");
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const fd = openSync("/dev/tty", "r");
     const ttyInput = new tty.ReadStream(fd);
     const rl = readline.createInterface({
@@ -665,7 +685,7 @@ function handleRetryLater() {
       if (!key && !str) return;
       if (str === "\r" || str === "\n" || str === "q" || str === "Q" || key?.name === "return" || key?.name === "q" || key?.name === "c" && key.ctrl) {
         cleanup();
-        resolve2();
+        resolve3();
       }
     };
     ttyInput.on("keypress", handleKeypress);
@@ -729,6 +749,10 @@ async function handleCommandExecutionError(error, options) {
     });
     process.exit(1);
   }
+  if (error instanceof InsufficientBalanceError) {
+    console.error(error.formatMessage());
+    process.exit(1);
+  }
   const message = error instanceof Error ? error.message : String(error);
   console.error(`Error: Failed to start command execution. ${message}`);
   process.exit(1);
@@ -740,6 +764,81 @@ import * as os2 from "os";
 import * as path2 from "path";
 import { parse } from "smol-toml";
 
+// ../shared/async-race.ts
+async function* raceAsyncIterators({
+  iterators,
+  signal,
+  onError
+}) {
+  if (iterators.length === 0) {
+    return;
+  }
+  if (signal?.aborted) {
+    return;
+  }
+  const abortPromise = signal ? new Promise((resolve3) => {
+    signal.addEventListener("abort", () => resolve3(null), { once: true });
+  }) : null;
+  const pending = /* @__PURE__ */ new Map();
+  const startNext = (index) => {
+    const iterator = iterators[index];
+    if (!iterator) {
+      return;
+    }
+    pending.set(
+      index,
+      iterator.next().then(
+        (result) => ({ kind: "result", index, result }),
+        (error) => ({ kind: "error", index, error })
+      )
+    );
+  };
+  const throwOrContinue = (error, index) => {
+    if (!onError) {
+      throw error;
+    }
+    const decision = onError(index, error);
+    if (decision === "throw") {
+      throw error;
+    }
+  };
+  try {
+    for (let index = 0; index < iterators.length; index++) {
+      startNext(index);
+    }
+    while (pending.size > 0) {
+      const winner = abortPromise ? await Promise.race([
+        ...pending.values(),
+        abortPromise.then(() => null)
+      ]) : await Promise.race([...pending.values()]);
+      if (winner === null) {
+        return;
+      }
+      const { index } = winner;
+      pending.delete(index);
+      if (winner.kind === "error") {
+        throwOrContinue(winner.error, winner.index);
+        continue;
+      }
+      const { result } = winner;
+      if (!result.done) {
+        startNext(index);
+        yield { index, result };
+      }
+    }
+  } finally {
+    for (const iterator of iterators) {
+      try {
+        await iterator.return?.();
+      } catch {
+      }
+    }
+    for (const promise of pending.values()) {
+      promise.catch(() => void 0);
+    }
+  }
+}
+
 // lib/vcs-message-generator.ts
 var DEFAULT_MODELS = [
   // "mistral/ministral-3b",
@@ -750,14 +849,7 @@ var DEFAULT_MODELS = [
 ];
 var isAbortError = (error) => error instanceof Error && error.name === "AbortError";
 var isInvalidCliSessionIdError = (error) => error instanceof Error && error.message.includes("Invalid cliSessionId");
-var delay = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
-var createAbortPromise = (signal) => signal ? new Promise((resolve2) => {
-  if (signal.aborted) {
-    resolve2(null);
-    return;
-  }
-  signal.addEventListener("abort", () => resolve2(null), { once: true });
-}) : null;
+var delay = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 async function* generateCommitMessages(options) {
   const {
     diff,
@@ -765,13 +857,18 @@ async function* generateCommitMessages(options) {
     signal,
     cliSessionId,
     commandExecutionPromise,
-    useStream = false
+    useStream = false,
+    streamCaptureRecorder
   } = options;
   const resolvedCliSessionId = cliSessionId;
   if (!resolvedCliSessionId) {
     throw new Error("Missing cliSessionId for generate request.");
   }
   const requiredCliSessionId = resolvedCliSessionId;
+  const captureGenerationId = streamCaptureRecorder?.startGeneration({
+    cliSessionId: requiredCliSessionId,
+    models
+  });
   const token = await getToken();
   if (!token) {
     console.error("Error: Not authenticated. Run `ultrahope login` first.");
@@ -781,10 +878,18 @@ async function* generateCommitMessages(options) {
   const generateWithRetry = async function* (payload) {
     const maxAttempts = 3;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const attemptNumber = attempt + 1;
       try {
         for await (const event of api.streamCommitMessage(payload, {
           signal
         })) {
+          if (captureGenerationId != null) {
+            streamCaptureRecorder?.recordEvent(captureGenerationId, {
+              model: payload.model,
+              attempt: attemptNumber,
+              event
+            });
+          }
           log("generate", event);
           yield event;
         }
@@ -820,7 +925,8 @@ async function* generateCommitMessages(options) {
       for await (const event of generateWithRetry({
         cliSessionId: requiredCliSessionId,
         input: diff,
-        model
+        model,
+        guide: options.guide
       })) {
         if (event.type === "commit-message") {
           lastCommitMessage = event.commitMessage;
@@ -858,55 +964,36 @@ async function* generateCommitMessages(options) {
       if (isInvalidCliSessionIdError(error)) throw error;
     }
   }
-  const iterators = models.map((model, index) => ({
-    iterator: generateForModel(model, index)[Symbol.asyncIterator](),
-    index
-  }));
-  const pending = /* @__PURE__ */ new Map();
-  const startNext = (it) => {
-    const promise = it.iterator.next().then((result) => ({
-      result,
-      index: it.index
-    }));
-    pending.set(it.index, {
-      iterator: it.iterator,
-      promise,
-      index: it.index
-    });
-  };
-  for (const it of iterators) {
-    startNext(it);
-  }
-  const abortPromise = createAbortPromise(signal);
+  const iterators = models.map(
+    (model, index) => generateForModel(model, index)[Symbol.asyncIterator]()
+  );
   try {
-    while (pending.size > 0) {
-      if (signal?.aborted) break;
-      const next = Promise.race(
-        Array.from(pending.values()).map((p) => p.promise)
-      );
-      const winner = abortPromise ? await Promise.race([next, abortPromise]) : await next;
-      if (!winner || signal?.aborted) break;
-      const { result, index } = winner;
-      const entry = pending.get(index);
-      if (!entry) continue;
-      if (result.done) {
-        pending.delete(index);
-      } else {
-        yield result.value;
-        startNext({ iterator: entry.iterator, index });
+    for await (const { result } of raceAsyncIterators({
+      iterators,
+      signal,
+      onError(index, error) {
+        if (isAbortError(error) || signal?.aborted) {
+          return "continue";
+        }
+        void index;
+        return "throw";
       }
+    })) {
+      yield result.value;
     }
   } catch (error) {
     if (error instanceof InvalidModelError) {
       throw error;
     }
     if (error instanceof InsufficientBalanceError) {
-      console.error(
-        "Error: Token balance exhausted. Upgrade your plan at https://ultrahope.dev/pricing"
-      );
+      console.error(error.formatMessage());
       process.exit(1);
     }
     throw error;
+  } finally {
+    if (captureGenerationId != null) {
+      streamCaptureRecorder?.finishGeneration(captureGenerationId);
+    }
   }
 }
 
@@ -1062,6 +1149,52 @@ import { join as join4 } from "path";
 import * as readline3 from "readline";
 import * as tty2 from "tty";
 
+// ../shared/terminal-selector-helpers.ts
+function formatModelName(model) {
+  const parts = model.split("/");
+  return parts.length > 1 ? parts[1] : model;
+}
+function formatCost(cost) {
+  return `$${cost.toFixed(7).replace(/0+$/, "").replace(/\.$/, "")}`;
+}
+function formatTotalCostLabel(cost) {
+  return `$${cost.toFixed(6)}`;
+}
+function getReadyCount(slots) {
+  return slots.filter((slot) => slot.status === "ready").length;
+}
+function getTotalCost(slots) {
+  return slots.reduce((sum, slot) => {
+    if (slot.status === "ready" && slot.candidate.cost != null) {
+      return sum + slot.candidate.cost;
+    }
+    return sum;
+  }, 0);
+}
+function getLatestQuota(slots) {
+  for (const slot of slots) {
+    if (slot.status === "ready" && slot.candidate.quota) {
+      return slot.candidate.quota;
+    }
+  }
+  return void 0;
+}
+function hasReadySlot(slots) {
+  return getReadyCount(slots) > 0;
+}
+function selectNearestReady(slots, startIndex, direction) {
+  for (let index = startIndex + direction; index >= 0 && index < slots.length; index += direction) {
+    if (slots[index]?.status === "ready") {
+      return index;
+    }
+  }
+  return startIndex;
+}
+function getSelectedCandidate(slots, selectedIndex) {
+  const slot = slots[selectedIndex];
+  return slot?.status === "ready" ? slot.candidate : void 0;
+}
+
 // lib/renderer.ts
 import * as readline2 from "readline";
 var SPINNER_FRAMES = [
@@ -1121,47 +1254,6 @@ function createRenderer(output) {
 
 // lib/selector.ts
 var TTY_PATH = "/dev/tty";
-function formatModelName(model) {
-  const parts = model.split("/");
-  return parts.length > 1 ? parts[1] : model;
-}
-function formatCost(cost) {
-  return `$${cost.toFixed(7).replace(/0+$/, "").replace(/\.$/, "")}`;
-}
-function getReadyCount(slots) {
-  return slots.filter((s) => s.status === "ready").length;
-}
-function getTotalCost(slots) {
-  return slots.reduce((sum, slot) => {
-    if (slot.status === "ready" && slot.candidate.cost != null) {
-      return sum + slot.candidate.cost;
-    }
-    return sum;
-  }, 0);
-}
-function getLatestQuota(slots) {
-  for (const slot of slots) {
-    if (slot.status === "ready" && slot.candidate.quota) {
-      return slot.candidate.quota;
-    }
-  }
-  return void 0;
-}
-function hasReadySlot(slots) {
-  return slots.some((s) => s.status === "ready");
-}
-function getSelectedCandidate(slots, selectedIndex) {
-  const slot = slots[selectedIndex];
-  return slot?.status === "ready" ? slot.candidate : void 0;
-}
-function selectNearestReady(slots, startIndex, direction) {
-  for (let i = startIndex + direction; i >= 0 && i < slots.length; i += direction) {
-    if (slots[i]?.status === "ready") {
-      return i;
-    }
-  }
-  return startIndex;
-}
 function collapseToReady(slots) {
   const readySlots = slots.filter((s) => s.status === "ready");
   slots.length = 0;
@@ -1176,6 +1268,11 @@ function formatSlot(slot, selected) {
     const meta2 = slot.model ? `${theme.dim}     ${formatModelName(slot.model)}${theme.reset}` : "";
     return meta2 ? [line2, meta2] : [line2];
   }
+  if (slot.status === "error") {
+    const radio2 = "\u25CB";
+    const line2 = `${theme.dim}  ${radio2}  ${slot.content}${theme.reset}`;
+    return [line2];
+  }
   const candidate = slot.candidate;
   const title = candidate.content.split("\n")[0]?.trim() || "";
   const modelInfo = candidate.model ? candidate.cost ? `${formatModelName(candidate.model)} ${formatCost(candidate.cost)}` : formatModelName(candidate.model) : "";
@@ -1190,9 +1287,6 @@ function formatSlot(slot, selected) {
   const meta = modelInfo ? `${theme.dim}     ${modelInfo}${theme.reset}` : "";
   return meta ? [line, meta] : [line];
 }
-function formatTotalCostLabel(cost) {
-  return `$${cost.toFixed(6)}`;
-}
 function renderSelector(state, nowMs, renderer) {
   const { slots, selectedIndex, isGenerating, totalSlots } = state;
   const lines = [];
@@ -1244,7 +1338,7 @@ function renderError(error, slots, totalSlots, output) {
   }
 }
 function openEditor(content) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const editor = process.env.GIT_EDITOR || process.env.EDITOR || "vi";
     const tmpDir = mkdtempSync(join4(tmpdir(), "ultrahope-"));
     const tmpFile = join4(tmpDir, "EDIT_MESSAGE");
@@ -1258,7 +1352,7 @@ function openEditor(content) {
       }
       const result = readFileSync2(tmpFile, "utf-8").trim();
       unlinkSync(tmpFile);
-      resolve2(result);
+      resolve3(result);
     });
     child.on("error", (err) => {
       try {
@@ -1318,12 +1412,12 @@ async function selectCandidate(options) {
   );
 }
 async function selectFromSlots(initialSlots, asyncCtx, ttyIo) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let resolved = false;
     const resolveOnce = (result) => {
       if (resolved) return;
       resolved = true;
-      resolve2(result);
+      resolve3(result);
     };
     const slots = [...initialSlots];
     const state = {
@@ -1383,10 +1477,10 @@ async function selectFromSlots(initialSlots, asyncCtx, ttyIo) {
     };
     const nextCandidate = async (iterator) => {
       const abortPromise = new Promise(
-        (resolve3) => {
+        (resolve4) => {
           asyncCtx?.abortController.signal.addEventListener(
             "abort",
-            () => resolve3({ done: true, value: void 0 }),
+            () => resolve4({ done: true, value: void 0 }),
             { once: true }
           );
         }
@@ -1411,9 +1505,12 @@ async function selectFromSlots(initialSlots, asyncCtx, ttyIo) {
             const result = await nextCandidate(iterator);
             if (result.done || cleanedUp) break;
             const candidate = result.value;
-            const targetIndex = slots.findIndex(
-              (slot) => slot.status === "pending" ? slot.slotId === candidate.slotId : slot.candidate.slotId === candidate.slotId
-            );
+            const targetIndex = slots.findIndex((slot) => {
+              if (slot.status === "ready") {
+                return slot.candidate.slotId === candidate.slotId;
+              }
+              return slot.status === "pending" && slot.slotId === candidate.slotId;
+            });
             if (targetIndex >= 0 && targetIndex < slots.length) {
               const isNewSlot = slots[targetIndex].status === "pending";
               updateState((draft) => {
@@ -1554,7 +1651,162 @@ async function selectFromSlots(initialSlots, asyncCtx, ttyIo) {
   });
 }
 
+// lib/stream-capture.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, resolve as resolve2 } from "path";
+var noopRecorder = {
+  enabled: false,
+  startGeneration: () => 0,
+  recordEvent: () => {
+  },
+  finishGeneration: () => {
+  },
+  flush: () => null
+};
+function sanitizeEvent(event) {
+  if (event.type === "provider-metadata") {
+    return {
+      type: "provider-metadata",
+      providerMetadata: event.providerMetadata
+    };
+  }
+  if (event.type === "usage") {
+    return {
+      type: "usage",
+      usage: {
+        inputTokens: event.usage.inputTokens,
+        outputTokens: event.usage.outputTokens,
+        totalTokens: event.usage.totalTokens
+      }
+    };
+  }
+  if (event.type === "commit-message") {
+    return {
+      type: "commit-message",
+      commitMessage: event.commitMessage
+    };
+  }
+  return {
+    type: "error",
+    message: event.message
+  };
+}
+function toSerializableCapture(capture) {
+  return {
+    ...capture,
+    runs: capture.runs.map((run) => ({
+      ...run,
+      args: [...run.args],
+      generations: run.generations.map((generation) => ({
+        ...generation,
+        models: [...generation.models],
+        events: generation.events.map((event) => ({
+          atMs: event.atMs,
+          model: event.model,
+          attempt: event.attempt,
+          event: sanitizeEvent(event.event)
+        }))
+      }))
+    }))
+  };
+}
+function createStreamCaptureRecorder(options) {
+  if (!options.path) {
+    return noopRecorder;
+  }
+  const outputPath = resolve2(process.cwd(), options.path);
+  const runStartedAtMs = Date.now();
+  const run = {
+    id: "run-1",
+    command: options.command,
+    args: options.args,
+    apiPath: options.apiPath,
+    startedAt: new Date(runStartedAtMs).toISOString(),
+    generations: []
+  };
+  const capture = {
+    version: 2,
+    source: "ultrahope-commit-message-stream",
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    runs: [run]
+  };
+  let generationSequence = 0;
+  let runFinished = false;
+  const activeGenerations = /* @__PURE__ */ new Map();
+  const writeCapture = () => {
+    capture.capturedAt = (/* @__PURE__ */ new Date()).toISOString();
+    mkdirSync2(dirname3(outputPath), { recursive: true });
+    writeFileSync2(
+      outputPath,
+      `${JSON.stringify(toSerializableCapture(capture), null, 2)}
+`,
+      "utf-8"
+    );
+  };
+  const ensureRunFinished = () => {
+    if (runFinished) {
+      return;
+    }
+    runFinished = true;
+    run.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  };
+  return {
+    enabled: true,
+    startGeneration: ({ cliSessionId, models }) => {
+      generationSequence += 1;
+      const startedAtMs = Date.now();
+      const generation = {
+        id: `generation-${generationSequence}`,
+        cliSessionId,
+        models: [...models],
+        startedAt: new Date(startedAtMs).toISOString(),
+        events: []
+      };
+      run.generations.push(generation);
+      activeGenerations.set(generationSequence, { generation, startedAtMs });
+      return generationSequence;
+    },
+    recordEvent: (generationId, record) => {
+      const activeGeneration = activeGenerations.get(generationId);
+      if (!activeGeneration) {
+        return;
+      }
+      const eventAtMs = typeof record.event.atMs === "number" && Number.isFinite(record.event.atMs) ? record.event.atMs : Date.now() - activeGeneration.startedAtMs;
+      activeGeneration.generation.events.push({
+        atMs: Math.max(0, Math.round(eventAtMs)),
+        model: record.model,
+        attempt: record.attempt,
+        event: sanitizeEvent(record.event)
+      });
+    },
+    finishGeneration: (generationId) => {
+      const activeGeneration = activeGenerations.get(generationId);
+      if (!activeGeneration) {
+        return;
+      }
+      activeGeneration.generation.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+      activeGenerations.delete(generationId);
+      writeCapture();
+    },
+    flush: () => {
+      for (const [generationId, activeGeneration] of activeGenerations) {
+        activeGeneration.generation.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+        activeGenerations.delete(generationId);
+      }
+      ensureRunFinished();
+      writeCapture();
+      return outputPath;
+    }
+  };
+}
+
 // commands/commit.ts
+function normalizeGuide(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  return trimmed.length > 1024 ? trimmed.slice(0, 1024) : trimmed;
+}
 function exitWithInvalidModelError(error) {
   console.error(`Error: Model '${error.model}' is not supported.`);
   if (error.allowedModels.length > 0) {
@@ -1573,6 +1825,8 @@ function showQuotaInfo(quota) {
 }
 function parseArgs(args2) {
   let cliModels;
+  let captureStreamPath;
+  let guide;
   for (let i = 0; i < args2.length; i++) {
     const arg = args2[i];
     if (arg === "--models") {
@@ -1583,12 +1837,29 @@ function parseArgs(args2) {
       }
       cliModels = parseModelsArg(value);
       i++;
+    } else if (arg === "--capture-stream") {
+      const value = args2[i + 1];
+      if (!value) {
+        console.error("Error: --capture-stream requires a file path");
+        process.exit(1);
+      }
+      captureStreamPath = value;
+      i++;
+    } else if (arg === "--guide") {
+      const value = args2[i + 1];
+      if (!value) {
+        console.error("Error: --guide requires a text value.");
+        process.exit(1);
+      }
+      guide = normalizeGuide(value);
+      i++;
     }
   }
   return {
-    message: args2.includes("-m") || args2.includes("--message"),
     interactive: !args2.includes("--no-interactive"),
-    cliModels
+    cliModels,
+    captureStreamPath,
+    guide
   };
 }
 function getStagedDiff() {
@@ -1601,31 +1872,6 @@ function getStagedDiff() {
     process.exit(1);
   }
 }
-function openEditor2(initialMessage) {
-  return new Promise((resolve2, reject) => {
-    const editor = process.env.GIT_EDITOR || process.env.EDITOR || "vi";
-    const tmpDir = mkdtempSync2(join5(tmpdir2(), "ultrahope-"));
-    const tmpFile = join5(tmpDir, "COMMIT_EDITMSG");
-    writeFileSync2(tmpFile, initialMessage);
-    const child = spawn2(editor, [tmpFile], {
-      stdio: "inherit"
-    });
-    child.on("close", (code) => {
-      if (code !== 0) {
-        unlinkSync2(tmpFile);
-        reject(new Error(`Editor exited with code ${code}`));
-        return;
-      }
-      const message = readFileSync3(tmpFile, "utf-8").trim();
-      unlinkSync2(tmpFile);
-      resolve2(message);
-    });
-    child.on("error", (err) => {
-      unlinkSync2(tmpFile);
-      reject(err);
-    });
-  });
-}
 function commitWithMessage(message) {
   try {
     execSync2(`git commit -m ${JSON.stringify(message)}`, { stdio: "inherit" });
@@ -1635,6 +1881,12 @@ function commitWithMessage(message) {
 }
 async function commit(args2) {
   const options = parseArgs(args2);
+  const captureRecorder = createStreamCaptureRecorder({
+    path: options.captureStreamPath,
+    command: "git ultrahope commit",
+    args: ["commit", ...args2],
+    apiPath: "/v1/commit-message/stream"
+  });
   const models = resolveModels(options.cliModels);
   const diff = getStagedDiff();
   if (!diff.trim()) {
@@ -1643,131 +1895,123 @@ async function commit(args2) {
     );
     process.exit(1);
   }
-  const token = await getToken();
-  if (!token) {
-    console.error("Error: Not authenticated. Run `ultrahope login` first.");
-    process.exit(1);
-  }
-  const api = createApiClient(token);
-  const {
-    commandExecutionPromise: promise,
-    abortController,
-    cliSessionId: id
-  } = startCommandExecution({
-    api,
-    command: "commit",
-    args: args2,
-    apiPath: "/v1/commit-message",
-    requestPayload: {
-      input: diff,
-      target: "vcs-commit-message",
-      models
+  try {
+    const token = await getToken();
+    if (!token) {
+      console.error("Error: Not authenticated. Run `ultrahope login` first.");
+      process.exit(1);
     }
-  });
-  const cliSessionId = id;
-  const commandExecutionSignal = abortController.signal;
-  const commandExecutionPromise = promise;
-  const apiClient = api;
-  commandExecutionPromise.catch(async (error) => {
-    abortController.abort(abortReasonForError(error));
-    await handleCommandExecutionError(error, {
-      progress: { ready: 0, total: models.length }
+    const api = createApiClient(token);
+    const {
+      commandExecutionPromise: promise,
+      abortController,
+      cliSessionId: id
+    } = startCommandExecution({
+      api,
+      command: "commit",
+      args: args2,
+      apiPath: "/v1/commit-message",
+      requestPayload: {
+        input: diff,
+        target: "vcs-commit-message",
+        model: models[0],
+        ...options.guide ? { guide: options.guide } : {}
+      }
     });
-  });
-  const recordSelection = async (generationId) => {
-    if (!generationId || !apiClient) return;
-    try {
-      await apiClient.recordGenerationScore({
-        generationId,
-        value: 1
+    const cliSessionId = id;
+    const commandExecutionSignal = abortController.signal;
+    const commandExecutionPromise = promise;
+    const apiClient = api;
+    commandExecutionPromise.catch(async (error) => {
+      abortController.abort(abortReasonForError(error));
+      await handleCommandExecutionError(error, {
+        progress: { ready: 0, total: models.length }
       });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (message.includes("Generation not found")) {
-        return;
+    });
+    const recordSelection = async (generationId) => {
+      if (!generationId || !apiClient) return;
+      try {
+        await apiClient.recordGenerationScore({
+          generationId,
+          value: 1
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("Generation not found")) {
+          return;
+        }
+        console.error(`Warning: Failed to record selection. ${message}`);
       }
-      console.error(`Warning: Failed to record selection. ${message}`);
-    }
-  };
-  const createCandidates = (signal) => generateCommitMessages({
-    diff,
-    models,
-    signal: mergeAbortSignals(signal, commandExecutionSignal),
-    cliSessionId,
-    commandExecutionPromise
-  });
-  if (!options.interactive) {
-    const gen = generateCommitMessages({
+    };
+    const createCandidates = (signal) => generateCommitMessages({
       diff,
-      models: models.slice(0, 1),
-      signal: commandExecutionSignal,
+      models,
+      guide: options.guide,
+      signal: mergeAbortSignals(signal, commandExecutionSignal),
       cliSessionId,
-      commandExecutionPromise
+      commandExecutionPromise,
+      streamCaptureRecorder: captureRecorder
     });
-    const first = await gen.next().catch((error) => {
-      if (error instanceof InvalidModelError) {
-        exitWithInvalidModelError(error);
-      }
-      throw error;
-    });
-    await recordSelection(first.value?.generationId);
-    const message = first.value?.content ?? "";
-    if (options.message) {
+    if (!options.interactive) {
+      const gen = generateCommitMessages({
+        diff,
+        models: models.slice(0, 1),
+        guide: options.guide,
+        signal: commandExecutionSignal,
+        cliSessionId,
+        commandExecutionPromise,
+        streamCaptureRecorder: captureRecorder
+      });
+      const first = await gen.next().catch((error) => {
+        if (error instanceof InvalidModelError) {
+          exitWithInvalidModelError(error);
+        }
+        throw error;
+      });
+      await recordSelection(first.value?.generationId);
+      const message = first.value?.content ?? "";
       commitWithMessage(message);
       return;
     }
-    const editedMessage = await openEditor2(message);
-    if (!editedMessage) {
-      console.error("Aborting commit due to empty message.");
-      process.exit(1);
-    }
-    commitWithMessage(editedMessage);
-    return;
-  }
-  const stats = getGitStagedStats();
-  console.log(ui.success(`Found ${formatDiffStats(stats)}`));
-  while (true) {
-    const result = await selectCandidate({
-      createCandidates,
-      maxSlots: models.length,
-      abortSignal: commandExecutionSignal,
-      models
-    });
-    if (result.action === "abort") {
-      if (result.error instanceof InvalidModelError) {
-        exitWithInvalidModelError(result.error);
+    const stats = getGitStagedStats();
+    console.log(ui.success(`Found ${formatDiffStats(stats)}`));
+    while (true) {
+      const result = await selectCandidate({
+        createCandidates,
+        maxSlots: models.length,
+        abortSignal: commandExecutionSignal,
+        models
+      });
+      if (result.action === "abort") {
+        if (result.error instanceof InvalidModelError) {
+          exitWithInvalidModelError(result.error);
+        }
+        if (isCommandExecutionAbort(commandExecutionSignal)) {
+          return;
+        }
+        console.error("Aborting commit.");
+        process.exit(1);
       }
-      if (isCommandExecutionAbort(commandExecutionSignal)) {
-        return;
+      if (result.action === "reroll") {
+        continue;
       }
-      console.error("Aborting commit.");
-      process.exit(1);
-    }
-    if (result.action === "reroll") {
-      continue;
-    }
-    if (result.action === "confirm" && result.selected) {
-      await recordSelection(result.selectedCandidate?.generationId);
-      const costLabel = result.totalCost != null ? ` (total: ${formatTotalCost(result.totalCost)})` : "";
-      console.log(ui.success(`Message selected${costLabel}`));
-      if (options.message) {
+      if (result.action === "confirm" && result.selected) {
+        await recordSelection(result.selectedCandidate?.generationId);
+        const costLabel = result.totalCost != null ? ` (total: ${formatTotalCost(result.totalCost)})` : "";
+        console.log(ui.success(`Message selected${costLabel}`));
         console.log(`${ui.success("Running git commit")}
 `);
         commitWithMessage(result.selected);
-      } else {
-        const editedMessage = await openEditor2(result.selected);
-        if (!editedMessage) {
-          console.error("Aborting commit due to empty message.");
-          process.exit(1);
+        if (result.quota) {
+          showQuotaInfo(result.quota);
         }
-        console.log(`${ui.success("Running git commit")}
-`);
-        commitWithMessage(editedMessage);
-      }
-      if (result.quota) {
-        showQuotaInfo(result.quota);
+        return;
       }
-      return;
+    }
+  } finally {
+    const capturePath = captureRecorder.flush();
+    if (capturePath) {
+      console.log(ui.hint(`Captured stream replay to ${capturePath}`));
     }
   }
 }
@@ -1797,14 +2041,16 @@ Commands:
    commit      Generate commit message from staged changes
 
 Commit options:
-   -m, --message     Commit directly with generated message
-   --no-interactive  Single candidate, open in editor
+   --no-interactive  Single candidate, commit directly
+   --guide <text>     Additional context to guide message generation
    --models <list>   Comma-separated model list (overrides config)
+   --capture-stream <path>  Save commit-message stream as replay JSON
 
 Examples:
    git ultrahope commit               # interactive selector (default)
-   git ultrahope commit -m            # select and commit directly
-   git ultrahope commit --no-interactive  # single candidate, open editor`);
+   git ultrahope commit --guide "GHSA-gq3j-xvxp-8hrf: override reason"
+   git ultrahope commit --capture-stream /tmp/git-commit-stream.capture.json
+   git ultrahope commit --no-interactive  # single candidate, commit directly`);
 }
 main().catch((err) => {
   console.error(err);