@crouton-kit/humanloop 0.3.8 → 0.3.9

package/dist/api.js

@@ -25,11 +25,17 @@ function buildSummary(deck, responses) {
         const ft = r.freetext !== undefined && r.freetext !== '' ? r.freetext : undefined;
         let picked;
         if (r.selectedOptionIds !== undefined) {
-            const labels = r.selectedOptionIds
+            const oc = r.optionComments;
+            const parts = r.selectedOptionIds
                 .map((id) => it.options.find((o) => o.id === id))
                 .filter((o) => o !== undefined)
-                .map((o) => o.label);
-            picked = labels.length > 0 ? labels.join(', ') : undefined;
+                .map((o) => {
+                const note = oc !== undefined ? oc[o.id] : undefined;
+                return typeof note === 'string' && note.length > 0
+                    ? `${o.label} ("${note}")`
+                    : o.label;
+            });
+            picked = parts.length > 0 ? parts.join(', ') : undefined;
         }
         else if (r.selectedOptionId !== undefined) {
             picked = it.options.find((o) => o.id === r.selectedOptionId)?.label;

package/dist/cli.js

@@ -244,6 +244,11 @@ const RESPONSE_SCHEMA = {
                     selectedOptionId: { type: 'string' },
                     selectedOptionIds: { type: 'array', items: { type: 'string' } },
                     freetext: { type: 'string' },
+                    optionComments: {
+                        type: 'object',
+                        description: 'Multi-select per-option comments, keyed by option id.',
+                        additionalProperties: { type: 'string' },
+                    },
                 },
             },
         },

package/dist/editor/review.d.ts

@@ -6,6 +6,23 @@ export interface ReviewOptions {
     editor?: string;
     /** Force running in the current terminal even when $TMUX is set. */
     noTmux?: boolean;
+    /**
+     * When set, an explicit `<Space>s` / `:HLSubmit` invocation writes a sentinel
+     * file at this path. Node-side uses the file's existence to gate `submitted: true`.
+     * When omitted, any editor exit finalizes `submitted: true` (legacy behavior).
+     */
+    submitFlagPath?: string;
+    /**
+     * When true and $TMUX is set and !opts.noTmux, launch via
+     * `tmux display-popup -E` instead of `tmux split-window`.
+     * display-popup -E is synchronous so no poll loop is needed.
+     */
+    tmuxPopup?: boolean;
+    /** Override the default 90%/90% popup size. Only used when tmuxPopup is true. */
+    popupSize?: {
+        w: string;
+        h: string;
+    };
 }
 /**
  * Compact stdout rendering for the agent: per comment just the line:col

package/dist/editor/review.js

@@ -179,6 +179,9 @@ function reviewVimscript() {
         ``,
         `function! s:Submit() abort`,
         `  call s:Save()`,
+        `  if $HL_SUBMIT_FLAG !=# ''`,
+        `    call writefile([''], $HL_SUBMIT_FLAG)`,
+        `  endif`,
         `  qa!`,
         `endfunction`,
         ``,
@@ -285,7 +288,24 @@ function rangeLabel(c) {
 export function formatFeedbackSummary(result, feedbackJsonPath) {
     const n = result.comments.length;
     const out = [];
-    if (n === 0) {
+    if (!result.submitted) {
+        if (n > 0) {
+            out.push(`hl propose — draft saved: ${n} comment${n === 1 ? '' : 's'} on ${result.file} (not yet submitted)`);
+            out.push('');
+            result.comments.forEach((c, i) => {
+                const original = c.quote && c.quote.length > 0 ? c.quote : c.lineText;
+                const lines = original.split('\n');
+                out.push(` ${i + 1}. ${rangeLabel(c)}`);
+                lines.forEach((ln, k) => out.push(k === 0 ? `    text:    ${ln}` : `             ${ln}`));
+                out.push(`    comment: ${c.comment}`);
+                out.push('');
+            });
+        }
+        else {
+            out.push(`hl propose — draft saved: no comments yet on ${result.file}`);
+        }
+    }
+    else if (n === 0) {
         out.push(`hl propose — approved: 0 comments on ${result.file} (human signalled looks-good; proceed)`);
     }
     else {
@@ -367,7 +387,12 @@ export async function launchReview(file, opts) {
     const dir = mkdtempSync(join(tmpdir(), 'hl-review-'));
     const initPath = join(dir, 'review.vim');
     writeFileSync(initPath, reviewVimscript());
-    const env = { ...process.env, HL_OUTPUT: outPath, HL_SOURCE: absFile };
+    const env = {
+        ...process.env,
+        HL_OUTPUT: outPath,
+        HL_SOURCE: absFile,
+        ...(opts.submitFlagPath ? { HL_SUBMIT_FLAG: opts.submitFlagPath } : {}),
+    };
     // `-u NONE`: do NOT load the user's init.lua / LazyVim / plugins / keymaps.
     // Default runtimepath still includes the config dir (for the gloam
     // colorscheme) and the site dir (for the treesitter markdown parser), so the
@@ -382,16 +407,27 @@ export async function launchReview(file, opts) {
     if (inTmux) {
         // `exec env …` so the editor replaces the shell and becomes the pane's
         // process (so tmux `#{pane_current_command}` is `nvim`, not the shell).
+        const envPairs = [
+            `HL_OUTPUT=${shellQuote(outPath)}`,
+            `HL_SOURCE=${shellQuote(absFile)}`,
+            ...(opts.submitFlagPath ? [`HL_SUBMIT_FLAG=${shellQuote(opts.submitFlagPath)}`] : []),
+        ];
         const paneCmd = [
             'exec',
             'env',
-            `HL_OUTPUT=${shellQuote(outPath)}`,
-            `HL_SOURCE=${shellQuote(absFile)}`,
+            ...envPairs,
             shellQuote(bin),
             ...editorArgs.map(shellQuote),
         ].join(' ');
         try {
-            await runInTmuxPane(paneCmd);
+            if (opts.tmuxPopup) {
+                const w = opts.popupSize ? opts.popupSize.w : '90%';
+                const h = opts.popupSize ? opts.popupSize.h : '90%';
+                execFileSync('tmux', ['display-popup', '-E', '-w', w, '-h', h, paneCmd], { stdio: 'inherit' });
+            }
+            else {
+                await runInTmuxPane(paneCmd);
+            }
         }
         catch (err) {
             process.stderr.write(`tmux dispatch failed, running in current terminal: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -412,12 +448,13 @@ export async function launchReview(file, opts) {
         }
     }
     const now = new Date().toISOString();
+    const didSubmit = opts.submitFlagPath ? existsSync(opts.submitFlagPath) : true;
     const result = {
         file: absFile,
-        submitted: true,
-        approved: comments.length === 0,
+        submitted: didSubmit,
+        approved: didSubmit && comments.length === 0,
         comments,
-        submittedAt: now,
+        ...(didSubmit ? { submittedAt: now } : {}),
         savedAt: now,
     };
     atomicWrite(outPath, JSON.stringify(result, null, 2) + '\n');

package/dist/tui/input.js

@@ -177,15 +177,37 @@ function handleInteractionAction(input, key, state, interaction, render) {
         render();
         return;
     }
-    // Comment mode: allowFreetext + options exist. Multi-select carries its
-    // checked set on submit, so don't pre-attach a single option.
+    // Comment mode: allowFreetext + options exist.
+    //
+    // Single-select: pre-attach the focused option (the comment qualifies that
+    // pick). Multi-select: also pre-attach the focused option — the comment is
+    // saved under `optionComments[id]` (per-option note) and submitting
+    // auto-checks the option. From the [c] freetext row in multi-select,
+    // start with no attachment so the comment becomes the overall freetext.
     if (input === 'c' && interaction.allowFreetext && opts.length > 0) {
-        const preselected = !interaction.multiSelect && state.selectedAction < opts.length
-            ? opts[state.selectedAction].id
-            : undefined;
-        state.inputMode = preselected !== undefined
-            ? { kind: 'comment', buffer: '', selectedOptionId: preselected }
-            : { kind: 'comment', buffer: '' };
+        const onOption = state.selectedAction < opts.length;
+        if (onOption) {
+            const optId = opts[state.selectedAction].id;
+            let prefill = '';
+            if (interaction.multiSelect) {
+                const existing = state.responses.get(interaction.id);
+                const prior = existing?.optionComments?.[optId];
+                if (typeof prior === 'string')
+                    prefill = prior;
+            }
+            state.inputMode = { kind: 'comment', buffer: prefill, selectedOptionId: optId };
+        }
+        else {
+            // On the [c] row in multi-select: pre-fill from existing overall freetext.
+            let prefill = '';
+            if (interaction.multiSelect) {
+                const existing = state.responses.get(interaction.id);
+                if (existing !== undefined && typeof existing.freetext === 'string') {
+                    prefill = existing.freetext;
+                }
+            }
+            state.inputMode = { kind: 'comment', buffer: prefill };
+        }
         render();
         return;
     }
@@ -250,6 +272,18 @@ function handleInputMode(input, key, state, render) {
     }
     if (key.return) {
         const interaction = state.interactions[state.currentIndex];
+        const perOption = interaction.multiSelect === true
+            && mode.kind === 'comment'
+            && mode.selectedOptionId !== undefined;
+        if (perOption) {
+            // Per-option comment: save under optionComments[id], auto-check the
+            // option (idempotent), stay on this interaction so the human can comment
+            // on another option.
+            setOptionComment(state, interaction, mode.selectedOptionId, mode.buffer);
+            state.inputMode = null;
+            render();
+            return;
+        }
         if (interaction.multiSelect) {
             commitMulti(state, interaction, mode.buffer);
         }
@@ -361,14 +395,20 @@ function submitOption(state, interaction, selectedOptionId, freetext) {
 // submitOption immediacy); Enter just confirms the accumulated set + advances.
 function toggleMulti(state, interaction, optionId) {
     const existing = state.responses.get(interaction.id);
-    const set = new Set(existing?.selectedOptionIds ?? []);
+    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
+        ? existing.selectedOptionIds
+        : [];
+    const set = new Set(priorIds);
     if (set.has(optionId))
         set.delete(optionId);
     else
         set.add(optionId);
     const response = { id: interaction.id, selectedOptionIds: [...set] };
-    if (existing?.freetext !== undefined)
+    if (existing !== undefined && existing.freetext !== undefined)
         response.freetext = existing.freetext;
+    if (existing !== undefined && existing.optionComments !== undefined) {
+        response.optionComments = { ...existing.optionComments };
+    }
     state.responses.set(interaction.id, response);
     // User edited the checked set — no longer a passive carry-over.
     state.preAnsweredIds.delete(interaction.id);
@@ -378,15 +418,52 @@ function toggleMulti(state, interaction, optionId) {
  *  answered, optionally setting/replacing freetext. */
 function commitMulti(state, interaction, freetext) {
     const existing = state.responses.get(interaction.id);
+    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
+        ? existing.selectedOptionIds
+        : [];
     const response = {
         id: interaction.id,
-        selectedOptionIds: [...(existing?.selectedOptionIds ?? [])],
+        selectedOptionIds: [...priorIds],
     };
-    const ft = freetext ?? existing?.freetext;
+    let ft;
+    if (freetext !== undefined)
+        ft = freetext;
+    else if (existing !== undefined)
+        ft = existing.freetext;
     if (ft !== undefined)
         response.freetext = ft;
+    if (existing !== undefined && existing.optionComments !== undefined) {
+        response.optionComments = { ...existing.optionComments };
+    }
     state.responses.set(interaction.id, response);
     // Explicit confirm overrides any preAnswered seed.
     state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }
+/**
+ * Multi-select per-option comment: write `comment` to optionComments[optionId]
+ * and auto-check the option. Empty comment still records the entry (the user
+ * committed deliberately via Enter; Esc cancels without write).
+ */
+function setOptionComment(state, interaction, optionId, comment) {
+    const existing = state.responses.get(interaction.id);
+    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
+        ? existing.selectedOptionIds
+        : [];
+    const set = new Set(priorIds);
+    set.add(optionId);
+    const priorComments = existing !== undefined && existing.optionComments !== undefined
+        ? existing.optionComments
+        : {};
+    const nextComments = { ...priorComments, [optionId]: comment };
+    const response = {
+        id: interaction.id,
+        selectedOptionIds: [...set],
+        optionComments: nextComments,
+    };
+    if (existing !== undefined && existing.freetext !== undefined)
+        response.freetext = existing.freetext;
+    state.responses.set(interaction.id, response);
+    state.preAnsweredIds.delete(interaction.id);
+    state.persist?.();
+}

package/dist/tui/render.js

@@ -289,10 +289,11 @@ export function renderItemReview(state, cols, rows) {
         const label = interaction.freetextLabel !== undefined
             ? interaction.freetextLabel
             : state.inputMode.kind === 'comment' ? 'Comment' : 'Response';
-        // Show attached option (single-select comment mode only) — Tab cycles.
-        // Multi-select comments carry the checked set, so no attach line.
+        // Show attached option in comment mode. For single-select the comment
+        // qualifies the pick; for multi-select an attached option means the
+        // comment is saved as a per-option note (and auto-checks the option).
         let attachedLine;
-        if (state.inputMode.kind === 'comment' && !interaction.multiSelect) {
+        if (state.inputMode.kind === 'comment') {
             const attachedId = state.inputMode.selectedOptionId;
             const opts = interaction.options;
             if (opts.length > 0) {
@@ -301,7 +302,7 @@ export function renderItemReview(state, cols, rows) {
                     : undefined;
                 const valueText = attached !== undefined
                     ? `${CYAN}${singleLine(attached.label)}${RESET}`
-                    : `${DIM}none${RESET}`;
+                    : `${DIM}none (overall)${RESET}`;
                 attachedLine = `  ${DIM}attached:${RESET} ${valueText}  ${DIM}[tab to cycle]${RESET}`;
             }
         }
@@ -382,10 +383,11 @@ function renderActions(interaction, selectedAction, maxW, existing) {
     const prefixWidth = multi ? 12 : 8;
     const indent = ' '.repeat(prefixWidth);
     const contentMax = Math.max(20, maxW - prefixWidth);
+    const optionComments = existing !== undefined ? existing.optionComments : undefined;
     for (let i = 0; i < opts.length; i++) {
         const o = opts[i];
         const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-        const sc = o.shortcut ?? ' ';
+        const sc = o.shortcut === undefined ? ' ' : o.shortcut;
         const keyBadge = `${DIM}[${sc}]${RESET}`;
         const box = multi
             ? (checked.has(o.id) ? `${GREEN}[x]${RESET}` : `${DIM}[ ]${RESET}`) + ' '
@@ -401,10 +403,25 @@ function renderActions(interaction, selectedAction, maxW, existing) {
                 lines.push(`${indent}${DIM}${dl}${RESET}`);
             }
         }
+        if (multi && optionComments !== undefined) {
+            const note = optionComments[o.id];
+            if (typeof note === 'string' && note.length > 0) {
+                const noteLines = wrap(`✎ ${sanitize(note)}`, contentMax);
+                for (const nl of noteLines) {
+                    lines.push(`${indent}${YELLOW}${nl}${RESET}`);
+                }
+            }
+        }
     }
     if (interaction.allowFreetext && opts.length > 0) {
         const cursor = opts.length === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-        const label = interaction.freetextLabel !== undefined ? interaction.freetextLabel : 'Add comment';
+        let label;
+        if (interaction.freetextLabel !== undefined)
+            label = interaction.freetextLabel;
+        else if (multi)
+            label = 'Add overall comment  (c on an option for per-option)';
+        else
+            label = 'Add comment';
         lines.push(`  ${cursor} ${DIM}[c]${RESET} ${label}`);
     }
     else if (interaction.allowFreetext && opts.length === 0) {
@@ -463,11 +480,17 @@ export function renderFinal(state, cols, rows) {
 }
 export function responseSummary(r, interaction) {
     if (r.selectedOptionIds !== undefined) {
-        const labels = r.selectedOptionIds
+        const oc = r.optionComments;
+        const parts = r.selectedOptionIds
             .map((id) => interaction.options.find((o) => o.id === id))
             .filter((o) => o !== undefined)
-            .map((o) => sanitize(o.label));
-        const picks = labels.length > 0 ? labels.join(', ') : '(none)';
+            .map((o) => {
+            const note = oc !== undefined ? oc[o.id] : undefined;
+            return typeof note === 'string' && note.length > 0
+                ? `${sanitize(o.label)} ("${sanitize(note)}")`
+                : sanitize(o.label);
+        });
+        const picks = parts.length > 0 ? parts.join(', ') : '(none)';
         if (r.freetext)
             return `${picks}: "${sanitize(r.freetext)}"`;
         return picks;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { Key } from './tui/terminal.js';
-export type InteractionKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
+export type InteractionKind = 'notify' | 'validation' | 'decision' | 'context' | 'error' | 'review';
 export interface InteractionOption {
     id: string;
     label: string;
@@ -45,6 +45,10 @@ export interface InteractionResponse {
     /** Multi-select picks (set only for `multiSelect` interactions). */
     selectedOptionIds?: string[];
     freetext?: string;
+    /** Multi-select per-option comments, keyed by option id. Each entry is a
+     *  comment scoped to that specific option (independent of the overall
+     *  `freetext`). Set only for `multiSelect` interactions. */
+    optionComments?: Record<string, string>;
 }
 export interface DeckSource {
     sessionName?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",