@crouton-kit/humanloop 0.3.38 → 0.4.0

package/dist/api.d.ts

@@ -1,8 +1,8 @@
-import type { Deck, ResolutionEnvelope } from './types.js';
+import type { Deck, ResolutionEnvelope, VisualProvider } from './types.js';
 export interface AskOpts {
     /** Interaction directory. Defaults to a managed temp dir under os.tmpdir(). */
     dir?: string;
-    sessionId?: string;
+    visualProvider?: VisualProvider;
     cols?: number;
     rows?: number;
 }
@@ -18,6 +18,7 @@ export interface InboxOpts {
     cols?: number;
     rows?: number;
     roots?: string[];
+    visualProvider?: VisualProvider;
 }
 /** Open the centralized inbox controller in the current human terminal. */
 export declare function openInbox(opts?: InboxOpts): Promise<void>;

package/dist/api.js

@@ -27,7 +27,7 @@ export async function ask(deck, opts = {}) {
     stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
-        sessionId: opts.sessionId,
+        visualProvider: opts.visualProvider,
         cols: opts.cols,
         rows: opts.rows,
     });
@@ -48,6 +48,6 @@ export async function notify(title, body) {
 }
 /** 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 });
+    const controller = new InboxController({ roots: opts.roots, cols: opts.cols, rows: opts.rows, visualProvider: opts.visualProvider });
     await controller.run();
 }

package/dist/browser/server.d.ts

@@ -9,12 +9,18 @@ export interface WebServerOpts {
      * exactly once per server instance, only for the first accepted submit
      * (later submits get a 409 and never re-fire this). `responsePath`/
      * `completedAt` are already persisted to disk — the caller converges the
-     * host surface, it must NOT write the result again. Fired only after the
-     * submit's own HTTP 200 has finished flushing to its socket, so it is
-     * safe for this callback to `stop()` the server (which force-closes all
-     * open sockets) without racing the ack the browser is waiting on.
+     * host surface, it must NOT write the result again. For a connected caller,
+     * fires only after its HTTP 200 finishes, so this callback can `stop()` the
+     * server without racing that ack. If the client disconnects after accepted
+     * persistence, it fires without waiting for an impossible finish.
      */
-    onSubmit?: (responses: InteractionResponse[], completedAt: string, responsePath: string) => void;
+    onSubmit?: (responses: InteractionResponse[], completedAt: string, responsePath: string) => void | Promise<void>;
+    /** Controller-owned finalization for a claimed inbox ticket. When supplied,
+     * this server never writes response.json itself. */
+    finalize?: (responses: InteractionResponse[]) => Promise<{
+        completedAt: string;
+        responsePath: string;
+    }>;
 }
 export interface ReviewWebServerOpts {
     /** Shared review job dir — carries review.vim and progress.json. */
@@ -47,6 +53,10 @@ export interface WebServerHandle {
      *  acks (closed, network hiccup) can't hang take-back forever. Safe to call
      *  with zero open sockets (e.g. the browser was never opened). */
     requestTakeBack(): Promise<void>;
+    /** The accepted submit currently completing its HTTP ack and owner convergence,
+     * if one has crossed the server boundary. `true` means the normal submit
+     * finish path completed; `false` means finalization was rejected. */
+    pendingSubmitLifecycle?(): Promise<boolean> | undefined;
     /** Stop listening, close all sockets (WS and HTTP), and tear down. */
     stop(): Promise<void>;
 }

package/dist/browser/server.js

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 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 { deckPath, progressPath, readJson, writeResponse, clearProgress } from '../inbox/convention.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
@@ -118,6 +118,12 @@ async function startDeckServer(opts) {
     let deck = opts.deck;
     const dir = opts.dir;
     let submitted = null;
+    let submitting = false;
+    // Created synchronously when an accepted request enters its finalizer, then
+    // kept pending through response flush and async owner convergence. A
+    // take-back can therefore serialize with the complete submit lifecycle,
+    // rather than racing only its persistence portion.
+    let pendingSubmitLifecycle;
     const scaffold = createServerScaffold();
     scaffold.setHandler(async (req, res) => {
         const url = req.url ?? '/';
@@ -132,7 +138,9 @@ async function startDeckServer(opts) {
             const onDisk = readJson(deckPath(dir));
             if (onDisk !== null)
                 deck = onDisk;
-            sendJson(res, 200, { dir, deck });
+            const progress = readJson(progressPath(dir));
+            const responses = Array.isArray(progress?.responses) ? progress.responses : [];
+            sendJson(res, 200, { dir, deck, responses });
             return;
         }
         if (url === '/api/submit' && req.method === 'POST') {
@@ -156,22 +164,107 @@ async function startDeckServer(opts) {
                 sendJson(res, 409, { ok: false, error: 'already_submitted', ...submitted });
                 return;
             }
+            if (submitting) {
+                sendJson(res, 409, { ok: false, error: 'submit_in_progress' });
+                return;
+            }
+            submitting = true;
             const responses = parsed.responses;
-            const completedAt = new Date().toISOString();
-            // Canonical write — the exact helper the terminal path uses, so nothing
-            // downstream of response.json can tell which surface produced it.
-            const responsePath = writeResponse(dir, responses, completedAt, deck);
+            let resolveSubmitLifecycle;
+            let submitLifecycleSettled = false;
+            const settleSubmitLifecycle = (didSubmit) => {
+                if (submitLifecycleSettled)
+                    return;
+                submitLifecycleSettled = true;
+                resolveSubmitLifecycle(didSubmit);
+            };
+            pendingSubmitLifecycle = new Promise((resolve) => { resolveSubmitLifecycle = resolve; });
+            let completedAt;
+            let responsePath;
+            // Convergence (owner onSubmit) must run exactly once for a persisted
+            // success, regardless of whether the client is still connected. The
+            // `finish` gate below only exists to preserve ack-ordering for a live
+            // caller; once the client is gone there is no ordering to protect.
+            let convergenceStarted = false;
+            const runConvergence = () => {
+                if (convergenceStarted)
+                    return;
+                convergenceStarted = true;
+                void Promise.resolve(opts.onSubmit?.(responses, completedAt, responsePath)).then(() => settleSubmitLifecycle(true), () => settleSubmitLifecycle(false));
+            };
+            // Observe client disconnect BEFORE awaiting the finalizer. If the
+            // client leaves while finalization is still pending we must NOT declare
+            // the accepted submit lost — the finalizer may still persist, in which
+            // case convergence must run. Defer judgment until the finalizer settles.
+            let finalizePending = true;
+            let successReady = false;
+            let responseFinished = false;
+            let clientGone = false;
+            const onResponseFinished = () => {
+                responseFinished = true;
+                if (successReady && submitted !== null)
+                    runConvergence();
+            };
+            const onClientGone = () => {
+                // `writableFinished` only means end() was called; a peer can vanish
+                // before the `finish` event. Only finish proves the live caller got
+                // through the response boundary.
+                if (responseFinished)
+                    return;
+                if (finalizePending || !successReady) {
+                    clientGone = true; // decide once finalization and convergence broadcast settle
+                    return;
+                }
+                if (submitted !== null) {
+                    // Accepted submit persisted but the client left before its body
+                    // flushed — converge once; no live caller remains to protect.
+                    runConvergence();
+                }
+                else {
+                    // The finalizer rejected: the submit was genuinely lost.
+                    settleSubmitLifecycle(false);
+                }
+            };
+            req.once('aborted', onClientGone);
+            res.once('finish', onResponseFinished);
+            res.once('close', onClientGone);
+            res.once('error', onClientGone);
+            try {
+                if (opts.finalize !== undefined) {
+                    ({ completedAt, responsePath } = await opts.finalize(responses));
+                }
+                else {
+                    // Standalone browser handoff retains its direct local persistence.
+                    completedAt = new Date().toISOString();
+                    responsePath = writeResponse(dir, responses, completedAt, deck);
+                    clearProgress(dir);
+                }
+            }
+            catch (error) {
+                finalizePending = false;
+                submitting = false;
+                settleSubmitLifecycle(false);
+                sendJson(res, 400, { error: 'invalid_submit', message: error instanceof Error ? error.message : String(error) });
+                return;
+            }
+            finalizePending = false;
             submitted = { responsePath, completedAt };
-            clearProgress(dir);
-            // Await the flush BEFORE registering the finish callback that can
-            // trigger caller-side stop() — that ordering is what closes the race
-            // between a lost WS frame and the teardown it precedes.
+            // Broadcast convergence before permitting owner cleanup, so connected
+            // observers receive this state transition before the server can close.
             await scaffold.broadcast({ type: 'converged' });
+            successReady = true;
+            if (clientGone) {
+                // The client disconnected during finalization; converge now rather
+                // than waiting for a `finish` that will never fire. The 200 is
+                // best-effort — the socket may already be closed.
+                runConvergence();
+                sendJson(res, 200, { ok: true, responsePath, completedAt });
+                return;
+            }
             // Ack-ordering guarantee: the HTTP caller must always receive its 200
-            // body before any lifecycle teardown can close its socket.
-            res.once('finish', () => {
-                opts.onSubmit?.(responses, completedAt, responsePath);
-            });
+            // body before any lifecycle teardown can close its socket. The finish
+            // observer registered above converges then; `onClientGone` converges if
+            // the peer disappears before finish.
             sendJson(res, 200, { ok: true, responsePath, completedAt });
             return;
         }
@@ -192,6 +285,9 @@ async function startDeckServer(opts) {
         async requestTakeBack() {
             await scaffold.broadcast({ type: 'taken-back' });
         },
+        pendingSubmitLifecycle() {
+            return pendingSubmitLifecycle;
+        },
         stop() {
             return scaffold.stop();
         },

package/dist/editor/roundtrip.d.ts

@@ -0,0 +1,5 @@
+/** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
+export declare function editBufferInEditor(buffer: string): {
+    text: string;
+    error?: string;
+};

package/dist/editor/roundtrip.js

@@ -0,0 +1,36 @@
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
+export function editBufferInEditor(buffer) {
+    const tmpFile = join(tmpdir(), `hl-input-${randomUUID()}.txt`);
+    const editor = process.env.EDITOR || 'vi';
+    try {
+        writeFileSync(tmpFile, buffer);
+        // $EDITOR may be a shell fragment such as "code --wait".
+        const result = spawnSync('/bin/sh', ['-c', `${editor} "$1"`, 'sh', tmpFile], { stdio: 'inherit' });
+        if (result.error)
+            return { text: buffer, error: `$EDITOR ("${editor}") failed to launch: ${result.error.message}` };
+        if (result.signal !== null)
+            return { text: buffer, error: `$EDITOR ("${editor}") was killed by signal ${result.signal}` };
+        if (result.status === 127 || result.status === 126)
+            return { text: buffer, error: `$EDITOR ("${editor}") failed to launch (shell exit ${result.status})` };
+        if (result.status !== 0)
+            return { text: buffer, error: `$EDITOR ("${editor}") exited with status ${result.status}` };
+        let text = readFileSync(tmpFile, 'utf8');
+        if (text.endsWith('\n') && !buffer.endsWith('\n'))
+            text = text.slice(0, -1);
+        return { text };
+    }
+    catch (error) {
+        return { text: buffer, error: `$EDITOR round-trip failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch { /* best-effort cleanup */ }
+    }
+}

package/dist/inbox/completion.js

@@ -1,7 +1,6 @@
 import { readdirSync, statSync, unlinkSync } from 'node:fs';
-import { spawn } from 'node:child_process';
 import { basename, resolve } from 'node:path';
-import { atomicWriteJson, deliveryErrorPath, deliveryPath, responsePath, readJson, reviewPath, withExclusiveDirectoryLockAsync } from './convention.js';
+import { atomicWriteJson, deliveryErrorPath, deliveryPath, responsePath, readJson, reviewPath, runHandler, withExclusiveDirectoryLockAsync } from './convention.js';
 import { registeredInboxRoot } from './registry.js';
 import { readTicketResult, ticketRoot } from './tickets.js';
 import { validateReviewProjection } from './deck-schema.js';
@@ -12,31 +11,6 @@ function receiptMatches(dir) {
 function eventFor(root, dir, result) {
     return { schema: 'humanloop.completion/v1', root, dir, ticketId: basename(dir), kind: result.kind, outcome: result.kind === 'canceled' ? 'canceled' : 'resolved', responsePath: responsePath(dir) };
 }
-async function runHandler(command, args, event) {
-    await new Promise((resolvePromise, rejectPromise) => {
-        // stdout stays ignored (a handler acknowledges by exit code, never stdout),
-        // but stderr is captured so a nonzero exit surfaces the handler's own
-        // diagnostics in the delivery-error record instead of a bare exit code.
-        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] });
-        let stderr = '';
-        child.stderr?.on('data', (chunk) => { stderr += chunk; if (stderr.length > 8192)
-            stderr = stderr.slice(-8192); });
-        let timedOut = false;
-        const timeout = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 30_000);
-        child.once('error', (error) => { clearTimeout(timeout); rejectPromise(error); });
-        child.once('exit', (code, signal) => {
-            clearTimeout(timeout);
-            const detail = stderr.trim() === '' ? '' : `: ${stderr.trim()}`;
-            if (timedOut)
-                rejectPromise(new Error(`completion handler timed out after 30 seconds${detail}`));
-            else if (code === 0)
-                resolvePromise();
-            else
-                rejectPromise(new Error(`completion handler failed (${signal ?? code ?? 'unknown'})${detail}`));
-        });
-        child.stdin.end(`${JSON.stringify(event)}\n`);
-    });
-}
 function projectReview(dir, result) {
     if (result.kind !== 'review')
         return;

package/dist/inbox/controller.d.ts

@@ -1,4 +1,4 @@
-import type { InteractionResponse, TicketSummary } from '../types.js';
+import type { InteractionResponse, TicketSummary, VisualProvider } from '../types.js';
 import type { Key } from '../tui/terminal.js';
 import { startWebServer } from '../browser/server.js';
 export interface InboxControllerOptions {
@@ -9,6 +9,7 @@ export interface InboxControllerOptions {
     completeDeck?: (dir: string, responses: InteractionResponse[], token: string) => Promise<unknown>;
     startDeckBrowser?: typeof startWebServer;
     openBrowser?: (url: string) => void;
+    visualProvider?: VisualProvider;
 }
 type Screen = 'list' | 'detail';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
@@ -19,13 +20,25 @@ export declare class InboxController {
     private items;
     private selectedDir;
     private selectedIndex;
+    /** Scroll state belongs to the passive preview, never to an editable deck. */
+    private previewScrollOffset;
     private screen;
     private adapter;
+    private activeDeck;
     private reviewAdapter;
     private deckBrowser;
+    /** Blocks terminal input until browser finalization/shutdown is quiescent. */
+    private deckBrowserTakingBack;
+    /** The single accepted submit that crossed the browser boundary. */
+    private deckBrowserFinalizing;
     private deckBrowserStarting;
+    private deckBrowserStartingGeneration;
+    /** Invalidates an in-flight asynchronous browser start when ownership ends. */
+    private deckBrowserGeneration;
     private claim;
     private reconciling;
+    private visualReconciling;
+    private readonly visualCleanupExecutor;
     private suspended;
     private submittingDir;
     private stdinListener;
@@ -56,16 +69,24 @@ export declare class InboxController {
      *  in ReviewAdapter; the controller only owns the terminal handoff. */
     private activateReview;
     reloadSelectedDeck(): void;
+    private followUpHandlers;
+    private readDeck;
+    private followUpViewState;
+    private refreshFollowUp;
     /** Hand the selected deck to its browser surface while retaining this ticket's claim. */
     private openDeckBrowser;
-    /** The browser has atomically published the response; reconcile its owner delivery. */
+    /** Finalize through this controller's claim-safe lifecycle before HTTP acks. */
+    private finalizeDeckBrowser;
+    /** The browser has finalized through the controller; reconcile its owner delivery. */
     private finishDeckBrowser;
     /** Return browser authority to the terminal deck without changing its draft. */
     private takeBackDeckBrowser;
     close(): void;
     run(): Promise<void>;
     private complete;
-    /** Give the raw TTY to a child process (native review editor). */
+    /** The controller owns the terminal handoff and repaint around $EDITOR. */
+    private editActiveDeckInput;
+    /** Give the raw TTY to a child process (native review editor or $EDITOR). */
     private suspendForChild;
     /** Retake the TTY after the child exits and force a full repaint. */
     private resumeAfterChild;
@@ -73,10 +94,18 @@ export declare class InboxController {
     /** Owner-boundary reconciliation for resolved results still lacking an ack.
      *  Guarded so overlapping fs events cannot stack concurrent scans. */
     private reconcileRoots;
+    /** Reconciliation owns stale-claim retirement and durable cleanup, never a Visual start. */
+    private reconcileVisualWork;
+    /** Automatic ticket capability is deliberately marker + current-root-handler only. */
+    private visualProviderFor;
+    private startTicketVisual;
     private leaveDetail;
     private select;
+    private scrollPreview;
     private detailSize;
     private detailLines;
+    private passiveDetailLines;
+    private previewViewport;
     private withStatus;
     private repaint;
     private watchRoots;