@crouton-kit/humanloop 0.3.4 → 0.3.5

package/dist/cli.js

@@ -9,6 +9,7 @@ import { launchReview } from './editor/review.js';
 import { validateDeck } from './inbox/deck-schema.js';
 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';
 // ── Version ───────────────────────────────────────────────────────────────────
@@ -297,6 +298,7 @@ program
     '  deck       — structured set of interactions (questions) for the human\n' +
     '  review     — freeform markdown document review with anchored comments\n' +
     '  view       — passive live render of a file in a tmux pane\n' +
+    '  doc        — render or validate directive-flavored markdown to stdout\n' +
     '  inbox      — list/resolve all pending interactions across root dirs\n' +
     '  job        — a running or completed kickoff (deck ask / review / inbox)\n' +
     '  schema     — JSON Schema for deck, resolution, or feedback payloads\n' +
@@ -305,6 +307,7 @@ program
     '  hl deck   — write questions, get answers      | use when: material decisions\n' +
     '  hl review — markdown doc review               | use when: doc feedback needed\n' +
     '  hl view   — live render in pane               | use when: displaying a file\n' +
+    '  hl doc    — render/validate to stdout         | use when: piping rendered markdown\n' +
     '  hl inbox  — browse pending interactions       | use when: clearing a backlog\n' +
     '  hl job    — inspect/wait/cancel running jobs  | use when: polling job output\n' +
     '  hl schema — print JSON Schemas                | use when: validating inputs\n' +
@@ -626,6 +629,79 @@ viewCmd
     }
     process.exit(0);
 });
+// ── doc ───────────────────────────────────────────────────────────────────────
+const docCmd = program.command('doc').description('Render or validate directive-flavored markdown to stdout.\n' +
+    '\n' +
+    'Children:\n' +
+    '  hl doc check  — validate directive syntax, no output | use when: preflighting before write\n' +
+    '  hl doc render — render markdown to ANSI/plain stdout | use when: piping rendered text to a file or consumer\n' +
+    '\n' +
+    'These wrap the pinned termrender binary that humanloop manages. Consumers\n' +
+    'should never call `termrender` directly — go through hl/SDK so there is one\n' +
+    'org-wide caller.\n');
+docCmd
+    .command('check')
+    .description('Validate directive-flavored markdown without rendering.\n' +
+    '\n' +
+    'stdin  { source?: string, path?: string }   exactly one required\n' +
+    'stdout { ok: bool, error?: string }\n' +
+    'exit   0 always (validation failures are not process errors)\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    const src = resolveDocSource(input);
+    const res = checkMarkdown(src);
+    process.stdout.write(JSON.stringify(res) + '\n');
+    process.exit(0);
+});
+docCmd
+    .command('render')
+    .description('Render directive-flavored markdown to ANSI or plain text on stdout.\n' +
+    '\n' +
+    'stdin  { source?: string, path?: string, width?: int=process.stdout.columns||100, color?: bool=true }\n' +
+    'stdout the rendered text (raw bytes; not JSON)\n' +
+    'exit   0 on success, non-zero on bad input\n' +
+    '\n' +
+    'When color=false, ANSI escape sequences are stripped from the output.\n' +
+    'Use this for feeding rendered content to other agents that need plain\n' +
+    'text without color codes.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    const src = resolveDocSource(input);
+    const width = typeof input.width === 'number' && input.width > 0
+        ? input.width
+        : (process.stdout.columns || 100);
+    const lines = renderMarkdown(src, width);
+    let out = lines.join('\n');
+    if (input.color === false) {
+        // Strip ANSI escape sequences for plain-text consumers.
+        // eslint-disable-next-line no-control-regex
+        out = out.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+    }
+    process.stdout.write(out);
+    if (!out.endsWith('\n'))
+        process.stdout.write('\n');
+    process.exit(0);
+});
+function resolveDocSource(input) {
+    const hasSource = typeof input.source === 'string' && input.source.length > 0;
+    const hasPath = typeof input.path === 'string' && input.path.length > 0;
+    if (hasSource === hasPath) {
+        emitError({
+            error: 'bad_input',
+            message: 'provide exactly one of {source, path}',
+            next: 'stdin like {"source": "..."} or {"path": "/abs/file.md"}',
+        });
+    }
+    if (hasSource)
+        return input.source;
+    const abs = resolve(input.path);
+    if (!existsSync(abs)) {
+        emitError({ error: 'file_not_found', message: `path not found: ${abs}`, next: 'check the path' });
+    }
+    return readFileSync(abs, 'utf-8');
+}
 // ── inbox ─────────────────────────────────────────────────────────────────────
 const inboxCmd = program.command('inbox').description('Browse and resolve pending interactions across root dirs.');
 inboxCmd

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

@@ -6,6 +6,12 @@ export declare const interactionOptionSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     shortcut: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const preAnswerSchema: z.ZodObject<{
+    selectedOptionId: z.ZodOptional<z.ZodString>;
+    selectedOptionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    freetext: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const deckSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodObject<{
@@ -35,6 +41,12 @@ export declare const deckSchema: z.ZodObject<{
             context: "context";
             error: "error";
         }>>;
+        preAnswered: z.ZodOptional<z.ZodObject<{
+            selectedOptionId: z.ZodOptional<z.ZodString>;
+            selectedOptionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            freetext: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function inlineBodyPath(deckPath: string, bodyPath: string): string;

package/dist/inbox/deck-schema.js

@@ -10,6 +10,12 @@ export const interactionOptionSchema = z.object({
     description: z.string().optional(),
     shortcut: z.string().optional(),
 });
+export const preAnswerSchema = z.object({
+    selectedOptionId: z.string().optional(),
+    selectedOptionIds: z.array(z.string()).optional(),
+    freetext: z.string().optional(),
+    label: z.string().optional(),
+});
 const interactionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
     title: z.string().min(1, { error: 'title must be non-empty' }),
@@ -21,6 +27,7 @@ const interactionSchema = z.object({
     allowFreetext: z.boolean().optional(),
     freetextLabel: z.string().optional(),
     kind: z.enum(['notify', 'validation', 'decision', 'context', 'error']).optional(),
+    preAnswered: preAnswerSchema.optional(),
 });
 const deckSourceSchema = z.object({
     sessionName: z.string().optional(),

package/dist/tui/app.js

@@ -18,12 +18,36 @@ function buildInitialState(deck) {
     // Single-question decks skip the overview list — there's nothing to overview,
     // and overview hides the option hotkeys so users press 'y' and nothing happens.
     const initialPhase = deck.interactions.length === 1 ? 'item-review' : 'overview';
+    const responses = new Map();
+    const preAnsweredIds = new Set();
+    // Seed responses + preAnsweredIds from any `preAnswered` field. The seeded
+    // response counts as answered for navigation/auto-advance, but is rendered
+    // distinctly so the human knows it carried over. `tryResume` runs after and
+    // takes priority — mid-deck progress should not be overwritten by defaults.
+    for (const interaction of deck.interactions) {
+        const pa = interaction.preAnswered;
+        if (pa === undefined)
+            continue;
+        const response = { id: interaction.id };
+        if (pa.selectedOptionId !== undefined)
+            response.selectedOptionId = pa.selectedOptionId;
+        if (pa.selectedOptionIds !== undefined)
+            response.selectedOptionIds = [...pa.selectedOptionIds];
+        if (pa.freetext !== undefined)
+            response.freetext = pa.freetext;
+        responses.set(interaction.id, response);
+        preAnsweredIds.add(interaction.id);
+    }
+    // Start cursor on the first unanswered interaction — humans land where they
+    // need to act. If every interaction is pre-answered, fall back to index 0.
+    const firstUnanswered = deck.interactions.findIndex((i) => !responses.has(i.id));
     return {
         phase: initialPhase,
-        currentIndex: 0,
+        currentIndex: firstUnanswered >= 0 ? firstUnanswered : 0,
         interactions: deck.interactions,
-        responses: new Map(),
+        responses,
         visuals: new Map(),
+        preAnsweredIds,
         inputMode: null,
         selectedAction: 0,
         detailExpanded: false,

package/dist/tui/input.js

@@ -173,7 +173,7 @@ function handleInteractionAction(input, key, state, interaction, render) {
             return;
         }
         submitOption(state, interaction, matched.id, undefined);
-        advanceItem(state, 1);
+        advanceToNextUnanswered(state);
         render();
         return;
     }
@@ -204,13 +204,13 @@ function handleInteractionAction(input, key, state, interaction, render) {
     if (key.return && state.selectedAction < opts.length) {
         if (interaction.multiSelect) {
             commitMulti(state, interaction);
-            advanceItem(state, 1);
+            advanceToNextUnanswered(state);
             render();
             return;
         }
         const o = opts[state.selectedAction];
         submitOption(state, interaction, o.id, undefined);
-        advanceItem(state, 1);
+        advanceToNextUnanswered(state);
         render();
         return;
     }
@@ -258,7 +258,7 @@ function handleInputMode(input, key, state, render) {
             submitOption(state, interaction, attached, mode.buffer);
         }
         state.inputMode = null;
-        advanceItem(state, 1);
+        advanceToNextUnanswered(state);
         render();
         return;
     }
@@ -320,6 +320,27 @@ function advanceItem(state, direction) {
     state.detailExpanded = false;
     state.scrollOffset = 0;
 }
+/**
+ * Move to the next interaction WITHOUT a response, falling through to the
+ * final phase if every following interaction is already answered (whether
+ * user-answered or `preAnswered`-seeded). Used by all post-submit advance
+ * sites so the human flies through pre-approved items by hitting Enter; raw
+ * `n`/`p` still step one at a time via `advanceItem`.
+ */
+function advanceToNextUnanswered(state) {
+    let next = state.currentIndex + 1;
+    while (next < state.interactions.length && state.responses.has(state.interactions[next].id)) {
+        next++;
+    }
+    if (next >= state.interactions.length) {
+        state.phase = 'final';
+        return;
+    }
+    state.currentIndex = next;
+    state.selectedAction = 0;
+    state.detailExpanded = false;
+    state.scrollOffset = 0;
+}
 function actionCount(interaction) {
     return interaction.options.length + (interaction.allowFreetext && interaction.options.length > 0 ? 1 : 0);
 }
@@ -330,6 +351,9 @@ function submitOption(state, interaction, selectedOptionId, freetext) {
     if (freetext !== undefined)
         response.freetext = freetext;
     state.responses.set(interaction.id, response);
+    // Explicit user submission overrides any preAnswered seed — flip the icon
+    // from "previously answered" to user-answered.
+    state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }
 // ── Multi-select ─────────────────────────────────────────────────────────────
@@ -346,6 +370,8 @@ function toggleMulti(state, interaction, optionId) {
     if (existing?.freetext !== undefined)
         response.freetext = existing.freetext;
     state.responses.set(interaction.id, response);
+    // User edited the checked set — no longer a passive carry-over.
+    state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }
 /** Ensure a (possibly empty) response exists so the interaction counts as
@@ -360,5 +386,7 @@ function commitMulti(state, interaction, freetext) {
     if (ft !== undefined)
         response.freetext = ft;
     state.responses.set(interaction.id, response);
+    // Explicit confirm overrides any preAnswered seed.
+    state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }

package/dist/tui/render.js

@@ -166,7 +166,10 @@ export function renderOverview(state, cols, rows) {
     for (let i = 0; i < state.interactions.length; i++) {
         const interaction = state.interactions[i];
         const response = state.responses.get(interaction.id);
-        const icon = response ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`;
+        const preAnswered = state.preAnsweredIds.has(interaction.id);
+        const icon = response
+            ? (preAnswered ? `${DIM}◆${RESET}` : `${GREEN}✓${RESET}`)
+            : `${DIM}○${RESET}`;
         const label = singleLine(interaction.title);
         const cursor = i === state.currentIndex ? `${CYAN}▸${RESET} ` : '  ';
         const labelMax = Math.max(10, cols - 16);
@@ -238,6 +241,16 @@ export function renderItemReview(state, cols, rows) {
             preLines.push(`  ${DIM}${line}${RESET}`);
         }
     }
+    // "Previously answered" marker — shown only while the seed is intact (no user
+    // override yet). The label comes from preAnswered.label so callers can be
+    // domain-specific ("Previously approved", "Carried over from prior pass").
+    if (state.preAnsweredIds.has(interaction.id)) {
+        const customLabel = interaction.preAnswered !== undefined ? interaction.preAnswered.label : undefined;
+        const label = typeof customLabel === 'string' && customLabel.length > 0
+            ? customLabel
+            : 'Previously answered';
+        preLines.push(`  ${DIM}${ITALIC}◆ ${sanitize(label)} — press n/p to review, or any option to override${RESET}`);
+    }
     // Body: rendered question body + expanded visual block (scrollable)
     const bodyLines = [];
     if (interaction.body) {
@@ -425,7 +438,10 @@ export function renderFinal(state, cols, rows) {
     const questionRows = [];
     for (const interaction of state.interactions) {
         const response = state.responses.get(interaction.id);
-        const icon = response ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
+        const preAnswered = state.preAnsweredIds.has(interaction.id);
+        const icon = response
+            ? (preAnswered ? `${DIM}◆${RESET}` : `${GREEN}✓${RESET}`)
+            : `${YELLOW}○${RESET}`;
         const label = singleLine(interaction.title);
         questionRows.push(`  ${icon} ${truncate(label, Math.max(10, maxW - 4))}`);
         if (response) {

package/dist/types.d.ts

@@ -6,6 +6,23 @@ export interface InteractionOption {
     description?: string;
     shortcut?: string;
 }
+/**
+ * Seed an interaction with an answer the caller already has on hand — e.g. a
+ * prior approval the human shouldn't have to re-confirm. When present, the
+ * panel: (a) populates `responses[id]` from these fields at mount, (b) renders
+ * a distinct "previously answered" marker in overview/final and labels it in
+ * item-review, and (c) skips past the interaction on post-submit auto-advance.
+ * The human can still navigate to it with `n`/`p` and override the seeded
+ * answer — once they do, it renders as user-answered.
+ */
+export interface InteractionPreAnswer {
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    /** One-line marker shown in the answered chrome (e.g. "Previously approved").
+     *  Defaults to "Previously answered" when omitted. */
+    label?: string;
+}
 export interface Interaction {
     id: string;
     title: string;
@@ -19,6 +36,7 @@ export interface Interaction {
     allowFreetext?: boolean;
     freetextLabel?: string;
     kind?: InteractionKind;
+    preAnswered?: InteractionPreAnswer;
 }
 export interface InteractionResponse {
     id: string;
@@ -84,6 +102,10 @@ export interface TuiState {
     interactions: Interaction[];
     responses: Map<string, InteractionResponse>;
     visuals: Map<string, VisualBlock>;
+    /** Ids of interactions whose response was seeded from `Interaction.preAnswered`
+     *  and which the human has not yet overridden. Drives the distinct
+     *  "previously answered" rendering and the skip-on-advance behavior. */
+    preAnsweredIds: Set<string>;
     inputMode: InputMode;
     selectedAction: number;
     detailExpanded: boolean;

package/package.json

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