@crouton-kit/humanloop 0.3.13 → 0.3.15

package/dist/api.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { resolveInteractionDir } from './tui/app.js';
 import { scanInbox } from './inbox/scan.js';
 import { pickFromInbox } from './inbox/tui.js';
-import { deckPath, atomicWriteJson, readJson } from './inbox/convention.js';
+import { deckPath, atomicWriteJson, readJson, stampCanvasNode } from './inbox/convention.js';
 import { getTerminalSize } from './tui/terminal.js';
 import { approveDeck, notifyDeck } from './inbox/deck-factories.js';
 const RESPONSE_SCHEMA_ID = 'humanloop.response/v2';
@@ -61,6 +61,7 @@ function buildSummary(deck, responses) {
 export async function ask(deck, opts = {}) {
     const dir = opts.dir ?? managedDir();
     mkdirSync(dir, { recursive: true });
+    stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
         sessionId: opts.sessionId,

package/dist/cli.js

@@ -11,7 +11,7 @@ import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
 import { renderMarkdown, checkMarkdown } from './render/termrender.js';
 import { scanInbox } from './inbox/scan.js';
-import { deckPath, atomicWriteJson, readJson, responsePath, } from './inbox/convention.js';
+import { deckPath, atomicWriteJson, readJson, responsePath, stampCanvasNode, } from './inbox/convention.js';
 // ── Version ───────────────────────────────────────────────────────────────────
 const HL_VERSION = '0.2.1';
 function emitError(err, exitCode = 1) {
@@ -212,7 +212,6 @@ const REQUEST_SCHEMA = {
                                 id: { type: 'string' },
                                 label: { type: 'string' },
                                 description: { type: 'string' },
-                                shortcut: { type: 'string', description: 'Single char. Auto-assigned if absent.' },
                             },
                         },
                     },
@@ -372,6 +371,7 @@ deckCmd
     }
     const dir = input.dir ? resolve(input.dir) : mkdtempSync(join(tmpdir(), 'hl-ix-'));
     mkdirSync(dir, { recursive: true });
+    stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const jobId = basename(dir);
     const visuals = input.visuals !== false;

package/dist/inbox/convention.d.ts

@@ -1,4 +1,4 @@
-import type { InteractionResponse } from '../types.js';
+import type { Deck, InteractionResponse } from '../types.js';
 export declare function deckPath(dir: string): string;
 export declare function responsePath(dir: string): string;
 export declare function progressPath(dir: string): string;
@@ -10,6 +10,15 @@ export declare function interactionState(dir: string): InteractionState;
 export declare function isResolved(dir: string): boolean;
 /** Returns true if a live resolver owns this dir (progress.json mtime < 300s). */
 export declare function isClaimed(dir: string): boolean;
+/**
+ * Stamp the originating canvas node id onto a deck's `source` so per-node
+ * attention scoping (crouter's nav chrome) can attribute the ask to the node
+ * that raised it rather than every sibling node sharing the same cwd.
+ *
+ * No-op when not inside a canvas node (CRTR_NODE_ID unset) or when the deck
+ * already carries a nodeId. Mutates `deck` in place.
+ */
+export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 export declare function readJson<T>(path: string): T | null;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string): string;

package/dist/inbox/convention.js

@@ -47,6 +47,23 @@ export function isClaimed(dir) {
         return false;
     }
 }
+// ── Canvas-node attribution ─────────────────────────────────────────
+/**
+ * Stamp the originating canvas node id onto a deck's `source` so per-node
+ * attention scoping (crouter's nav chrome) can attribute the ask to the node
+ * that raised it rather than every sibling node sharing the same cwd.
+ *
+ * No-op when not inside a canvas node (CRTR_NODE_ID unset) or when the deck
+ * already carries a nodeId. Mutates `deck` in place.
+ */
+export function stampCanvasNode(deck) {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '')
+        return;
+    if (deck.source?.nodeId != null && deck.source.nodeId !== '')
+        return;
+    deck.source = { ...(deck.source ?? {}), nodeId: id };
+}
 // ── Atomic I/O ────────────────────────────────────────────────────────────────
 export function atomicWriteJson(path, value) {
     const payload = JSON.stringify(value, null, 2);

package/dist/inbox/deck-schema.d.ts

@@ -4,7 +4,6 @@ export declare const interactionOptionSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    shortcut: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const preAnswerSchema: z.ZodObject<{
     selectedOptionId: z.ZodOptional<z.ZodString>;
@@ -18,6 +17,7 @@ export declare const deckSchema: z.ZodObject<{
         sessionName: z.ZodOptional<z.ZodString>;
         askedBy: z.ZodOptional<z.ZodString>;
         blockedSince: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     interactions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -29,7 +29,6 @@ export declare const deckSchema: z.ZodObject<{
             id: z.ZodString;
             label: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
-            shortcut: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         multiSelect: z.ZodOptional<z.ZodBoolean>;
         allowFreetext: z.ZodOptional<z.ZodBoolean>;

package/dist/inbox/deck-schema.js

@@ -8,7 +8,10 @@ export const interactionOptionSchema = z.object({
     id: z.string().min(1),
     label: z.string().min(1),
     description: z.string().optional(),
-    shortcut: z.string().optional(),
+    // No author-settable `shortcut`: option shortcuts are auto-assigned by the
+    // TUI (assignShortcuts). zod strips unknown keys, so any author-supplied
+    // `shortcut` is silently dropped here — this is the enforcement boundary that
+    // stops a deck from shadowing a reserved key (e.g. `c` = comment).
 });
 export const preAnswerSchema = z.object({
     selectedOptionId: z.string().optional(),
@@ -33,6 +36,7 @@ const deckSourceSchema = z.object({
     sessionName: z.string().optional(),
     askedBy: z.string().optional(),
     blockedSince: z.string().optional(),
+    nodeId: z.string().optional(),
 });
 export const deckSchema = z.object({
     title: z.string().optional(),

package/dist/tui/input.js

@@ -34,6 +34,10 @@ export function handleKeypress(input, key, state, render, exit) {
         exit();
         return;
     }
+    // Clear any transient hint from the previous keypress. Handlers below may set
+    // a fresh one (e.g. an empty multi-select Enter), so it survives exactly one
+    // render cycle.
+    state.hint = undefined;
     if (state.inputMode) {
         handleInputMode(input, key, state, render);
         checkAutoExit(state, exit);
@@ -53,9 +57,21 @@ export function handleKeypress(input, key, state, render, exit) {
     }
 }
 function checkAutoExit(state, exit) {
-    if (state.phase === 'final' && state.responses.size >= state.interactions.length) {
-        exit();
-    }
+    if (state.phase !== 'final')
+        return;
+    if (state.responses.size < state.interactions.length)
+        return;
+    // Multi-select commits route THROUGH the Summary/confirm screen instead of
+    // auto-exiting on the first Enter: the commit advances the deck to `final`,
+    // but the human must press Enter again (handleFinal) to actually submit.
+    // The interaction that pushed us into `final` is still at currentIndex — the
+    // advance helpers leave it there when they fall through to `final` — so a
+    // multi-select there means "just confirmed a set, await deliberate submit".
+    // Single-select keeps its submit-on-pick fast path (auto-exit below).
+    const justCommitted = state.interactions[state.currentIndex];
+    if (justCommitted?.multiSelect === true)
+        return;
+    exit();
 }
 // ── Overview ─────────────────────────────────────────────────────────────────
 function handleOverview(input, key, state, render, exit) {
@@ -225,6 +241,15 @@ function handleInteractionAction(input, key, state, interaction, render) {
     // and advances; single-select picks that one option.
     if (key.return && state.selectedAction < opts.length) {
         if (interaction.multiSelect) {
+            const checked = state.responses.get(interaction.id)?.selectedOptionIds ?? [];
+            if (checked.length === 0) {
+                // Accidental Enter with nothing toggled is a no-op: don't finalize or
+                // advance. A deliberate empty finish is still reachable via `q` →
+                // overview → finish (partial); freetext-only via the [c] row.
+                state.hint = 'Select at least one option (space to toggle), or q to skip';
+                render();
+                return;
+            }
             commitMulti(state, interaction);
             advanceToNextUnanswered(state);
             render();

package/dist/tui/render.js

@@ -322,6 +322,12 @@ export function renderItemReview(state, cols, rows) {
     else {
         postLines.push(...renderActions(interaction, state.selectedAction, maxW, response));
     }
+    // Transient hint (e.g. an empty multi-select Enter that was rejected). Sits
+    // just above the footer; cleared on the next keypress.
+    if (state.hint !== undefined && state.hint.length > 0) {
+        postLines.push('');
+        postLines.push(`  ${YELLOW}${sanitize(state.hint)}${RESET}`);
+    }
     // Window the body
     const reservedRows = preLines.length + postLines.length + 1; // +1 for footer
     const bodyHeight = Math.max(1, rows - reservedRows);

package/dist/types.d.ts

@@ -4,6 +4,9 @@ export interface InteractionOption {
     id: string;
     label: string;
     description?: string;
+    /** Auto-assigned by the TUI (assignShortcuts) — NOT author-settable. Omitted
+     *  from the deck schema so a deck can't create a shortcut that shadows a
+     *  reserved key (e.g. `c` = comment, which would submit+close on single-select). */
     shortcut?: string;
 }
 /**
@@ -54,6 +57,10 @@ export interface DeckSource {
     sessionName?: string;
     askedBy?: string;
     blockedSince?: string;
+    /** Originating canvas node id (CRTR_NODE_ID) when the ask was raised inside
+     *  a crouter canvas node. Lets per-node attention scoping attribute the ask
+     *  to the node that raised it rather than every sibling sharing the cwd. */
+    nodeId?: string;
 }
 export interface Deck {
     title?: string;
@@ -114,6 +121,9 @@ export interface TuiState {
     selectedAction: number;
     detailExpanded: boolean;
     scrollOffset: number;
+    /** Transient one-line notice shown in item-review (e.g. an empty multi-select
+     *  Enter that was rejected). Cleared on the next keypress. */
+    hint?: string;
     persist?: () => void;
 }
 /**

package/package.json

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