@crouton-kit/humanloop 0.3.33 → 0.3.34

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { Deck, ResolutionEnvelope, GenerateVisual } from './types.js';
+import type { Deck, ResolutionEnvelope } from './types.js';
 export interface AskOpts {
     /** Interaction directory. Defaults to a managed temp dir under os.tmpdir(). */
     dir?: string;
@@ -17,11 +17,7 @@ export declare function notify(title: string, body?: string): Promise<void>;
 export interface InboxOpts {
     cols?: number;
     rows?: number;
-    generateVisual?: GenerateVisual;
+    roots?: string[];
 }
-/**
- * List → resolve loop across `roots`. Shows pending interactions, lets the
- * human pick one, resolves it (writing its `response.json`), then rescans —
- * resolved items drop out — until the human quits or nothing is pending.
- */
-export declare function inbox(roots: string[], opts?: InboxOpts): Promise<void>;
+/** Open the centralized inbox controller in the current human terminal. */
+export declare function openInbox(opts?: InboxOpts): Promise<void>;

package/dist/api.js

@@ -2,11 +2,9 @@ import { mkdtempSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 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, stampCanvasNode } from './inbox/convention.js';
+import { InboxController } from './inbox/controller.js';
+import { deckPath, atomicWriteJson, stampCanvasNode } from './inbox/convention.js';
 import { resolveDeckBodyPaths } from './inbox/deck-schema.js';
-import { getTerminalSize } from './tui/terminal.js';
 import { notifyDeck } from './inbox/deck-factories.js';
 import { buildSummary } from './summary.js';
 const RESPONSE_SCHEMA_ID = 'humanloop.response/v2';
@@ -48,29 +46,8 @@ export async function notify(title, body) {
     const deck = notifyDeck(title, body !== undefined ? { body } : {});
     await ask(deck, {});
 }
-/**
- * List → resolve loop across `roots`. Shows pending interactions, lets the
- * human pick one, resolves it (writing its `response.json`), then rescans —
- * resolved items drop out — until the human quits or nothing is pending.
- */
-export async function inbox(roots, opts = {}) {
-    for (;;) {
-        const items = scanInbox(roots);
-        if (items.length === 0)
-            return;
-        const term = getTerminalSize();
-        const cols = opts.cols ?? term.cols;
-        const rows = opts.rows ?? term.rows;
-        const picked = await pickFromInbox(items, { cols, rows });
-        if (picked === null)
-            return;
-        const deck = readJson(deckPath(picked.dir));
-        if (deck === null)
-            continue; // raced/removed — rescan
-        await resolveInteractionDir(picked.dir, deck, {
-            generateVisual: opts.generateVisual,
-            cols,
-            rows,
-        });
-    }
+/** Open the centralized inbox controller in the current human terminal. */
+export async function openInbox(opts = {}) {
+    const controller = new InboxController({ roots: opts.roots, cols: opts.cols, rows: opts.rows });
+    await controller.run();
 }

package/dist/browser/server.d.ts

@@ -17,15 +17,15 @@ export interface WebServerOpts {
     onSubmit?: (responses: InteractionResponse[], completedAt: string, responsePath: string) => void;
 }
 export interface ReviewWebServerOpts {
-    /** Shared review job dir — carries review.vim and feedback.json. */
+    /** Shared review job dir — carries review.vim and progress.json. */
     jobDir: string;
     /** Absolute source file under review. */
     file: string;
-    /** Absolute feedback JSON output path. */
+    /** Absolute resumable review draft path. */
     output: string;
     /** Optional submit sentinel written on final browser submit. */
     submitFlagPath?: string;
-    /** Fired after the HTTP submit ack has finished flushing. */
+    /** Fired after the HTTP proposal ack has finished flushing. The controller owns finalization. */
     onSubmit?: (result: FeedbackResult, submittedAt: string, outputPath: string) => void;
     /** Test-only override for how long `requestTakeBack()` waits for open tabs
      *  to ack a flush before giving up and broadcasting `taken-back` anyway.

package/dist/browser/server.js

@@ -5,7 +5,7 @@ import { join, extname, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
 import { deckPath, readJson, writeResponse, clearProgress } from '../inbox/convention.js';
-import { buildDraftFeedbackResult, buildFinalFeedbackResult, parseFeedbackComments, readStoredDraftFeedbackResult, serializeFeedbackResult, writeFeedbackResult, writeSubmitFlag, } from '../editor/feedback.js';
+import { buildDraftFeedbackResult, buildFinalFeedbackResult, parseFeedbackComments, readReviewDraft, serializeFeedbackResult, writeReviewDraft, writeSubmitFlag, } from '../editor/feedback.js';
 // See $CRTR_CONTEXT_DIR/phase1-server-contract.md for the deck HTTP/WS API this
 // module implements — this file is the reference implementation for the deck
 // surface, and the review surface reuses the same static/WS skeleton.
@@ -201,20 +201,22 @@ async function startReviewServer(opts) {
     const { jobDir, file, output, submitFlagPath } = opts;
     const scaffold = createServerScaffold();
     let activated = false;
-    let version = 0;
+    const persistedDraft = readReviewDraft(output);
+    let version = persistedDraft?.version ?? 0;
     let ackWaiter = null;
     const TAKE_BACK_ACK_TIMEOUT_MS = opts.takeBackAckTimeoutMs ?? 2000;
-    let currentResult = readStoredDraftFeedbackResult(output, file)
-        ?? buildDraftFeedbackResult(file, [], new Date().toISOString());
+    let currentResult = buildDraftFeedbackResult(file, persistedDraft?.comments ?? [], persistedDraft?.savedAt ?? new Date().toISOString());
+    let proposed = false;
     function refreshInitialDraftFromDisk() {
-        if (version !== 0 || currentResult.submitted)
+        if (proposed)
             return;
-        const onDisk = readStoredDraftFeedbackResult(output, file);
-        if (onDisk === null)
+        const onDisk = readReviewDraft(output);
+        if (onDisk === null || onDisk.version < version)
             return;
-        if (serializeFeedbackResult(onDisk) !== serializeFeedbackResult(currentResult)) {
-            currentResult = onDisk;
-            version += 1;
+        const next = buildDraftFeedbackResult(file, onDisk.comments, onDisk.savedAt);
+        if (onDisk.version > version || serializeFeedbackResult(next) !== serializeFeedbackResult(currentResult)) {
+            currentResult = next;
+            version = onDisk.version;
         }
     }
     function currentSnapshot() {
@@ -297,7 +299,7 @@ async function startReviewServer(opts) {
                 return;
             }
             refreshInitialDraftFromDisk();
-            if (currentResult.submitted) {
+            if (proposed) {
                 sendJson(res, 409, { error: 'already_submitted', result: currentSnapshot() });
                 return;
             }
@@ -317,7 +319,7 @@ async function startReviewServer(opts) {
             const savedAt = new Date().toISOString();
             const nextResult = buildDraftFeedbackResult(file, parsedComments.comments, savedAt);
             try {
-                writeFeedbackResult(output, nextResult);
+                writeReviewDraft(output, parsedComments.comments, version + 1, savedAt);
             }
             catch (err) {
                 sendJson(res, 500, { error: 'internal', message: err instanceof Error ? err.message : String(err) });
@@ -343,14 +345,8 @@ async function startReviewServer(opts) {
                 return;
             }
             refreshInitialDraftFromDisk();
-            if (currentResult.submitted) {
-                sendJson(res, 409, {
-                    ok: false,
-                    error: 'already_submitted',
-                    output,
-                    submittedAt: currentResult.submittedAt,
-                    result: currentSnapshot(),
-                });
+            if (proposed) {
+                sendJson(res, 409, { ok: false, error: 'already_submitted', output, result: currentSnapshot() });
                 return;
             }
             if (!Number.isInteger(parsed.baseVersion)) {
@@ -369,11 +365,12 @@ async function startReviewServer(opts) {
             const submittedAt = new Date().toISOString();
             const nextResult = buildFinalFeedbackResult(file, parsedComments.comments, submittedAt);
             try {
-                writeFeedbackResult(output, nextResult);
-                currentResult = nextResult;
-                if (submitFlagPath !== undefined && submitFlagPath.length > 0) {
+                writeReviewDraft(output, parsedComments.comments, version + 1, submittedAt);
+                currentResult = buildDraftFeedbackResult(file, parsedComments.comments, submittedAt);
+                version += 1;
+                proposed = true;
+                if (submitFlagPath !== undefined && submitFlagPath.length > 0)
                     writeSubmitFlag(submitFlagPath);
-                }
             }
             catch (err) {
                 sendJson(res, 500, { error: 'internal', message: err instanceof Error ? err.message : String(err) });
@@ -384,7 +381,7 @@ async function startReviewServer(opts) {
             // between a lost WS frame and the teardown it precedes.
             await scaffold.broadcast({ type: 'converged' });
             res.once('finish', () => {
-                opts.onSubmit?.(currentSnapshot(), submittedAt, output);
+                opts.onSubmit?.(nextResult, submittedAt, output);
             });
             sendJson(res, 200, { ok: true, output, submittedAt, result: currentSnapshot() });
             return;