@crouton-kit/humanloop 0.3.38 → 0.4.0

package/dist/inbox/tui.js

@@ -19,33 +19,66 @@ export function formatTimeAgo(iso) {
     return 'just now';
 }
 /** Pure inbox rows; selection and terminal ownership belong to InboxController. */
-export function buildInboxLines(items, width, selectedIndex) {
+export function buildInboxLines(items, width, selectedIndex, height = Number.MAX_SAFE_INTEGER) {
     if (items.length === 0)
         return [`  ${DIM}${ITALIC}No pending interactions${RESET}`];
-    const lines = [`  ${BOLD}${items.length} pending${RESET}`, ''];
     const contentWidth = width - 4;
-    for (let index = 0; index < items.length; index++) {
-        const item = items[index];
-        const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
-        const icon = KIND_ICON[kind] ?? '·';
-        // Source and title share the row budget: an unbounded source (a long node
-        // or session name) would floor the title at its minimum and overflow the
-        // column, bending the panel divider. Shrink the source only when the row
-        // cannot hold it alongside the title's 10-col minimum.
-        const rawSource = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
-        const age = formatTimeAgo(item.blockedSince);
-        const source = truncateRow(rawSource, Math.max(8, contentWidth - age.length - 8 - 10));
-        const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
-        const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);
-        let row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} `;
-        if (source)
-            row += `${ansiColor(source, 'yellow')} ${DIM}·${RESET} `;
-        row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
-        lines.push(row);
-        if (item.claim)
-            lines.push(`      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`);
-        else if (item.subtitle)
-            lines.push(`      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`);
-    }
+    const itemLines = items.map((item, index) => buildItemLines(item, index, selectedIndex, contentWidth));
+    const window = visibleWindow(itemLines, selectedIndex, Math.max(1, height - 2));
+    const lines = [`  ${BOLD}${items.length} pending${RESET}`, ''];
+    if (window.start > 0)
+        lines.push(`  ${DIM}↑ ${window.start} above${RESET}`);
+    for (let index = window.start; index < window.end; index++)
+        lines.push(...itemLines[index]);
+    if (window.end < items.length)
+        lines.push(`  ${DIM}↓ ${items.length - window.end} below${RESET}`);
     return lines;
 }
+function buildItemLines(item, index, selectedIndex, contentWidth) {
+    const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
+    const icon = KIND_ICON[kind] ?? '·';
+    // Source and title share the row budget: an unbounded source (a long node
+    // or session name) would floor the title at its minimum and overflow the
+    // column, bending the panel divider. Shrink the source only when the row
+    // cannot hold it alongside the title's 10-col minimum.
+    const rawSource = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
+    const age = formatTimeAgo(item.blockedSince);
+    const source = truncateRow(rawSource, Math.max(8, contentWidth - age.length - 8 - 10));
+    const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
+    const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);
+    let row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} `;
+    if (source)
+        row += `${ansiColor(source, 'yellow')} ${DIM}·${RESET} `;
+    row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
+    if (item.claim)
+        return [row, `      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`];
+    if (item.subtitle)
+        return [row, `      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`];
+    return [row];
+}
+/** Select a contiguous row window that always contains the selected ticket. */
+function visibleWindow(rows, selectedIndex, capacity) {
+    let start = Math.max(0, Math.min(selectedIndex, rows.length - 1));
+    let end = start + 1;
+    let preferBelow = true;
+    while (true) {
+        const below = end < rows.length ? { start, end: end + 1 } : undefined;
+        const above = start > 0 ? { start: start - 1, end } : undefined;
+        const preferred = preferBelow ? [below, above] : [above, below];
+        const next = preferred.find((candidate) => candidate !== undefined && windowHeight(rows, candidate.start, candidate.end) <= capacity);
+        if (next === undefined)
+            break;
+        start = next.start;
+        end = next.end;
+        preferBelow = !preferBelow;
+    }
+    return { start, end };
+}
+function windowHeight(rows, start, end) {
+    let height = start > 0 ? 1 : 0;
+    for (let index = start; index < end; index++)
+        height += rows[index].length;
+    if (end < rows.length)
+        height++;
+    return height;
+}

package/dist/inbox/visual.d.ts

@@ -0,0 +1,130 @@
+import type { CanonicalInteraction, Interaction, VisualRequest as PanelVisualRequest } from '../types.js';
+import { type CompletionHandler } from './registry.js';
+export declare const VISUAL_CAPABILITY: "humanloop.visual/v1";
+export interface VisualClaimIdentity {
+    token: string;
+    host: string;
+    pid: number;
+    claimedAt: string;
+}
+export interface VisualCleanupObligation {
+    reason: 'canceled' | 'unreceipted_start_error';
+    attempts: number;
+    nextAttemptAt: string;
+    lastAttemptAt?: string;
+    lastError?: string;
+}
+interface VisualBinding {
+    capability: typeof VISUAL_CAPABILITY;
+    owner: string;
+    root: string;
+    dir: string;
+    ticketId: string;
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claim: VisualClaimIdentity;
+    handler: CompletionHandler;
+}
+export interface VisualProtocolRequest extends VisualBinding {
+    schema: 'humanloop.visual-request/v1';
+    state: 'running' | 'canceled' | 'terminal';
+    requestedAt: string;
+    settledAt?: string;
+    cleanup?: VisualCleanupObligation;
+}
+export interface VisualRequestEvent extends VisualBinding {
+    schema: 'humanloop.visual-request-event/v1';
+    action: 'start' | 'cancel';
+}
+interface VisualResultBinding extends VisualBinding {
+    schema: 'humanloop.visual-result/v1';
+    completedAt: string;
+}
+export type VisualProtocolResult = (VisualResultBinding & {
+    status: 'ready';
+    markdown: string;
+}) | (VisualResultBinding & {
+    status: 'error';
+    error: string;
+});
+export type VisualResultSubmission = {
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claimToken: string;
+    status: 'ready';
+    markdown: string;
+} | {
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claimToken: string;
+    status: 'error';
+    error: string;
+};
+export interface StartVisualRequestOptions {
+    root: string;
+    dir: string;
+    claimToken: string;
+    request: PanelVisualRequest;
+}
+export type VisualStartDeliveryResult = 'delivered' | 'already_attempted' | 'ineligible' | 'failed';
+export type VisualCleanupDeliveryResult = 'delivered' | 'pending' | 'none';
+export interface StartedVisualRequest {
+    request: VisualProtocolRequest;
+    /** Resolves after the one permitted start attempt reaches a determinate outcome. */
+    delivery: Promise<VisualStartDeliveryResult>;
+}
+export interface VisualCleanupTask {
+    root: string;
+    dir: string;
+    requestId: string;
+    reason: VisualCleanupObligation['reason'];
+    nextAttemptAt: string;
+}
+/** Normalize one Interaction into the sole persisted/event correlation shape. */
+export declare function canonicalizeInteraction(raw: Interaction | CanonicalInteraction): CanonicalInteraction;
+/** Stable bytes used for every interaction equality check across the protocol. */
+export declare function canonicalInteractionJson(raw: Interaction | CanonicalInteraction): string;
+export declare function parseVisualRequestEvent(raw: unknown): VisualRequestEvent;
+/** Strict, repairing reader; malformed or unbound request bytes return null. */
+export declare function readVisualRequest(root: string, dir: string, requestId: string): VisualProtocolRequest | null;
+/** Strict, repairing reader; canceled and mismatched results are never returned. */
+export declare function readVisualResult(root: string, dir: string, requestId: string): VisualProtocolResult | null;
+/** Decode an event and atomically bind it to Humanloop's immutable request state. */
+export declare function readVisualRequestForEvent(raw: unknown): VisualProtocolRequest | null;
+/** Persist one claim-bound request and dispatch its frozen handler at most once. */
+export declare function startVisualRequest(opts: StartVisualRequestOptions): StartedVisualRequest;
+/** Compare-publish the first fully correlated ready/error result. Stale writers are no-ops. */
+export declare function submitVisualResult(root: string, dir: string, raw: VisualResultSubmission): {
+    published: boolean;
+};
+/** Attempt one due cleanup delivery through the request's frozen handler. */
+export declare function dispatchVisualCleanup(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** State-first cancellation for one handle; the returned promise is cleanup delivery only. */
+export declare function cancelVisualRequest(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** State-first cancel every running request, then dispatch every owed cleanup (including start failures). */
+export declare function cancelVisualRequestsForTicket(root: string, dir: string): Promise<{
+    canceled: number;
+    cleanupOwed: number;
+}>;
+/** Durable tasks the next controller-owned retry executor should schedule. */
+export declare function listVisualCleanupObligations(root: string, dir: string): VisualCleanupTask[];
+export interface VisualRequestReconciliation {
+    retired: number;
+    cleanupOwed: number;
+    /** Cleanup delivery only; reconciliation never redelivers a start. */
+    delivery: Promise<VisualCleanupDeliveryResult[]>;
+}
+/** Retire abandoned generations under the ticket claim boundary. A live claim is
+ * authoritative; a newly acquired claim retires every older generation first. */
+export declare function reconcileVisualRequestsForTicket(root: string, dir: string, currentClaimToken?: string): VisualRequestReconciliation;
+/** Enumerate direct ticket children only, including resolved tickets whose cleanup is still owed. */
+export declare function listVisualCleanupObligationsForRoot(root: string): VisualCleanupTask[];
+/** Startup reconciliation only retires stale/missing-claim work; live owners stay untouched. */
+export declare function reconcileStaleVisualRequestsForRoot(root: string): VisualRequestReconciliation[];
+export {};