@crouton-kit/humanloop 0.1.0 → 0.1.3

package/dist/types.d.ts

@@ -1,50 +1,36 @@
-export type QuestionType = 'validation' | 'choice' | 'freetext';
-export interface ValidationQuestion {
+import type { Key } from './tui/terminal.js';
+export type InteractionKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
+export interface InteractionOption {
     id: string;
-    type: 'validation';
-    statement: string;
-    rationale: string;
+    label: string;
+    description?: string;
+    shortcut?: string;
 }
-export interface ChoiceQuestion {
+export interface Interaction {
     id: string;
-    type: 'choice';
-    question: string;
-    rationale: string;
-    options: string[];
+    title: string;
+    subtitle?: string;
+    body?: string;
+    bodyPath?: string;
+    options: InteractionOption[];
+    allowFreetext?: boolean;
+    freetextLabel?: string;
+    kind?: InteractionKind;
 }
-export interface FreetextQuestion {
+export interface InteractionResponse {
     id: string;
-    type: 'freetext';
-    question: string;
-    rationale: string;
+    selectedOptionId?: string;
+    freetext?: string;
 }
-export type Question = ValidationQuestion | ChoiceQuestion | FreetextQuestion;
-export interface DecisionsInput {
-    title?: string;
-    questions: Question[];
-}
-export interface ValidationAnswer {
-    id: string;
-    type: 'validation';
-    approved: boolean;
-    comment?: string;
-}
-export interface ChoiceAnswer {
-    id: string;
-    type: 'choice';
-    selected: string;
-    isCustom: boolean;
-    comment?: string;
-}
-export interface FreetextAnswer {
-    id: string;
-    type: 'freetext';
-    response: string;
+export interface DeckSource {
+    sessionName?: string;
+    askedBy?: string;
+    blockedSince?: string;
 }
-export type Answer = ValidationAnswer | ChoiceAnswer | FreetextAnswer;
-export interface DecisionsOutput {
-    answers: Answer[];
-    completedAt: string;
+export interface Deck {
+    title?: string;
+    source?: DeckSource;
+    interactions: Interaction[];
 }
 export interface VisualBlock {
     questionId: string;
@@ -55,18 +41,16 @@ export type Phase = 'overview' | 'item-review' | 'final';
 export type InputMode = null | {
     kind: 'comment';
     buffer: string;
+    selectedOptionId?: string;
 } | {
     kind: 'freetext';
     buffer: string;
-} | {
-    kind: 'custom-option';
-    buffer: string;
 };
 export interface TuiState {
     phase: Phase;
     currentIndex: number;
-    questions: Question[];
-    answers: Map<string, Answer>;
+    interactions: Interaction[];
+    responses: Map<string, InteractionResponse>;
     visuals: Map<string, VisualBlock>;
     inputMode: InputMode;
     selectedAction: number;
@@ -74,3 +58,31 @@ export interface TuiState {
     scrollOffset: number;
     persist?: () => void;
 }
+export type GenerateVisual = (interaction: Interaction) => Promise<{
+    ok: true;
+    ansi: string;
+    markdown: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export interface MountedPanelOpts {
+    deck: Deck;
+    progressPath?: string;
+    generateVisual?: GenerateVisual;
+    cols: number;
+    rows: number;
+    onProgress?: (responses: InteractionResponse[]) => void;
+    onComplete?: (responses: InteractionResponse[]) => void;
+    onExit?: () => void;
+}
+export interface MountedPanel {
+    handleKey(input: string, key: Key): void;
+    render(): string[];
+    handleResize(cols: number, rows: number): string[];
+    unmount(): void;
+    loadDeck(deck: Deck, opts?: {
+        progressPath?: string;
+    }): void;
+    canAcceptHostKeys(): boolean;
+}

package/dist/types.js

@@ -1,2 +1,2 @@
-// ── Input: what the agent writes ─────────────────────────────────────────────
+// ── v2 shapes (v1 schema dropped per cycle-16 user pivot — humanloop is v2-only) ──
 export {};

package/dist/visuals/generate.d.ts

@@ -1,4 +1,9 @@
-import type { Question, VisualBlock } from '../types.js';
-import type { ConversationMessage } from '../conversation/reader.js';
-export type VisualUpdateCallback = (questionId: string, block: VisualBlock) => void;
-export declare function generateVisuals(questions: Question[], conversation: ConversationMessage[], onUpdate: VisualUpdateCallback, width?: number): Promise<void>;
+import type { Interaction } from '../types.js';
+export declare function defaultGenerateVisual(interaction: Interaction, conversationContext: string): Promise<{
+    ok: true;
+    ansi: string;
+    markdown: string;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/visuals/generate.js

@@ -14,12 +14,12 @@ If one sentence captures the current state, write one sentence. If they need to
 
 # Directives (termrender-flavored markdown)
 
-  :::panel{title="T" color="c"}   Bordered box (colors: red|green|yellow|blue|magenta|cyan|white|gray)
-  :::tree{color="c"}               Indented hierarchy (2-space indent = nesting)
-  :::table                         Markdown table with borders
-  :::note / :::warning             Callouts
+  :::panel{title="T" color="c"}                 Bordered box (colors: red|green|yellow|blue|magenta|cyan|white|gray)
+  :::tree{color="c"}                            Indented hierarchy (2-space indent = nesting)
+  :::callout{type="info|warning|error|success"} Status callout with icon
+  ::::columns / :::col{width="50%"}             Side-by-side layout (use 4 colons on the outer columns)
 
-Each opens with ::: and closes with :::. Standard markdown also works: **bold**, *italic*, \`code\`, bullets.
+Each opens with ::: and closes with :::. GFM tables (\`| col | col |\` with a \`| --- |\` separator) render directly — no directive needed. Standard markdown also works: **bold**, *italic*, \`code\`, bullets.
 
 # Critical: ASCII art must live inside a :::panel
 
@@ -33,7 +33,7 @@ If the conversation doesn't contain enough context to write a grounded briefing,
 
 # Hard rules
 
-- Never nest directives (no :::panel containing :::table)
+- When nesting directives, the outer fence needs strictly more colons than the inner — e.g. \`::::columns\` wrapping \`:::col\`. Don't nest a panel inside a panel.
 - Never wrap output in backtick fences
 - Never repeat the question/statement text
 - Never write "tradeoffs to consider" or "here are some options"
@@ -93,37 +93,28 @@ function tryTermrender(markdown, width) {
         return null;
     }
 }
-export async function generateVisuals(questions, conversation, onUpdate, width = 72) {
-    const conversationText = conversation
-        .map(m => `${m.role}: ${m.content}`)
-        .join('\n\n');
-    const tasks = questions.map(async (question) => {
-        const questionText = question.type === 'validation'
-            ? `Decision to validate: "${question.statement}"\nRationale: ${question.rationale}`
-            : `Question: "${question.question}"\nRationale: ${question.rationale}${question.type === 'choice'
-                ? `\nOptions: ${question.options.join(', ')}`
-                : ''}`;
-        const prompt = `Here is the conversation so far:\n\n${conversationText}\n\n---\n\nGenerate a visual context block for this decision point:\n\n${questionText}`;
-        const result = await callHaiku(prompt, VISUAL_SYSTEM_PROMPT);
-        if (result) {
-            const cleaned = result
-                .replace(/^```[\w]*\n?/gm, '')
-                .replace(/^```\s*$/gm, '')
-                .trim();
-            const rendered = renderWithTermrender(cleaned, width);
-            onUpdate(question.id, {
-                questionId: question.id,
-                content: rendered,
-                status: 'ready',
-            });
-        }
-        else {
-            onUpdate(question.id, {
-                questionId: question.id,
-                content: '',
-                status: 'error',
-            });
-        }
-    });
-    await Promise.all(tasks);
+// defaultGenerateVisual matches the GenerateVisual contract for use with
+// mountPanel. Width is read from process.stdout.columns so callers that
+// embed humanloop in a sub-region should supply their own closure that bakes
+// in the correct width.
+export async function defaultGenerateVisual(interaction, conversationContext) {
+    const width = Math.max(40, Math.min((process.stdout.columns || 80) - 4, 76));
+    const optionsSummary = interaction.options.length > 0
+        ? `\nOptions: ${interaction.options.map((o) => o.label).join(' | ')}`
+        : '';
+    const subtitleLine = interaction.subtitle ? `\nContext: ${interaction.subtitle}` : '';
+    const questionText = `Title: "${interaction.title}"${subtitleLine}${optionsSummary}`;
+    const prompt = conversationContext
+        ? `Here is the conversation so far:\n\n${conversationContext}\n\n---\n\nGenerate a visual context block for this decision point:\n\n${questionText}`
+        : `Generate a visual context block for this decision point:\n\n${questionText}`;
+    const result = await callHaiku(prompt, VISUAL_SYSTEM_PROMPT);
+    if (result) {
+        const markdown = result
+            .replace(/^```[\w]*\n?/gm, '')
+            .replace(/^```\s*$/gm, '')
+            .trim();
+        const ansi = renderWithTermrender(markdown, width);
+        return { ok: true, ansi, markdown };
+    }
+    return { ok: false, error: 'haiku returned no output' };
 }

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "hl": "dist/cli.js"
   },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    }
+  },
   "files": [
     "dist",
     "commands"
@@ -13,7 +24,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli.ts",
-    "link": "npm link"
+    "link": "npm link",
+    "test": "tsx src/__tests__/mount-panel.test.ts"
   },
   "dependencies": {
     "@r-cli/sdk": "^1.3.0",