@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/human/types.d.ts

@@ -0,0 +1,136 @@
+export declare const INTERACTION_KINDS: readonly ["notify", "decision", "context", "error", "review"];
+export type InteractionKind = (typeof INTERACTION_KINDS)[number];
+export interface InteractionOption {
+    id: string;
+    label: string;
+    description?: string;
+    /** Auto-assigned by the TUI (assignShortcuts), never author-settable. */
+    shortcut?: string;
+}
+export interface InteractionPreAnswer {
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    /** One-line marker shown in the answered chrome. */
+    label?: string;
+}
+export interface Interaction {
+    id: string;
+    title: string;
+    subtitle: string;
+    body?: string;
+    bodyPath?: string;
+    options: InteractionOption[];
+    multiSelect?: boolean;
+    allowFreetext?: boolean;
+    freetextLabel?: string;
+    kind?: InteractionKind;
+    preAnswered?: InteractionPreAnswer;
+}
+export interface InteractionResponse {
+    id: string;
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    optionComments?: Record<string, string>;
+}
+export interface DeckSource {
+    sessionName?: string;
+    askedBy?: string;
+    blockedSince?: string;
+    /** Originating canvas node id (CRTR_NODE_ID) when the ask was raised inside a crouter canvas node. */
+    nodeId?: string;
+}
+export interface Deck {
+    title: string;
+    source?: DeckSource;
+    interactions: Interaction[];
+}
+export interface FeedbackComment {
+    id: string;
+    line: number;
+    endLine: number;
+    quote?: string;
+    colStart?: number;
+    colEnd?: number;
+    lineText: string;
+    comment: string;
+    createdAt: string;
+}
+export interface FeedbackResult {
+    file: string;
+    submitted: boolean;
+    approved: boolean;
+    comments: FeedbackComment[];
+    submittedAt?: string;
+    savedAt: string;
+}
+/**
+ * Resolution contract returned by `ask`/`inbox`. On-disk `response.json` stays
+ * `{ responses, completedAt }`; `responsePath` points at it.
+ */
+export interface ResolutionEnvelope {
+    summary: string;
+    responsePath: string;
+    schema: 'humanloop.response/v2';
+    responses: InteractionResponse[];
+    completedAt: string;
+}
+export interface ClaimSummary {
+    owner: string;
+    claimedAt: string;
+    heartbeatAt: string;
+}
+interface TicketSummaryBase {
+    dir: string;
+    id: string;
+    title: string;
+    subtitle: string;
+    blockedSince: string;
+    source: DeckSource;
+    claim?: ClaimSummary;
+}
+export interface DeckTicketSummary extends TicketSummaryBase {
+    kind: 'deck';
+    interactionKind?: InteractionKind;
+    interactionCount: number;
+}
+export interface ReviewTicketSummary extends TicketSummaryBase {
+    kind: 'review';
+    file: string;
+    output: string;
+}
+/** The only pending-ticket shape scanners expose. */
+export type TicketSummary = DeckTicketSummary | ReviewTicketSummary;
+export interface ReviewDescriptor {
+    schema: 'humanloop.review/v1';
+    file: string;
+    output: string;
+    title: string;
+    subtitle: string;
+    source: DeckSource;
+    blockedSince: string;
+}
+export interface DeckTicketResult {
+    schema: 'humanloop.response/v2';
+    kind: 'deck';
+    responses: InteractionResponse[];
+    summary: string;
+    completedAt: string;
+}
+export interface ReviewTicketResult {
+    schema: 'humanloop.review-response/v1';
+    kind: 'review';
+    result: FeedbackResult;
+    completedAt: string;
+}
+export interface CanceledTicketResult {
+    schema: 'humanloop.cancel/v1';
+    kind: 'canceled';
+    canceledAt: string;
+    reason?: string;
+    actor?: string;
+}
+/** The sole canonical response.json union. */
+export type TicketResult = DeckTicketResult | ReviewTicketResult | CanceledTicketResult;
+export {};

package/dist/core/human/types.js

@@ -0,0 +1,5 @@
+// ── v2 shapes (v1 schema dropped per cycle-16 user pivot — humanloop is v2-only) ──
+// Single source of truth for the interaction-kind enum: the Zod deck schema
+// (`deck-schema.ts`) and the CLI's JSON schema both derive their enum values
+// from this array so a new kind cannot drift between validation surfaces.
+export const INTERACTION_KINDS = ['notify', 'decision', 'context', 'error', 'review'];

package/dist/{clients/attach → core/human}/visible-paths.d.ts

@@ -1,6 +1,6 @@
 /** Extract existing file paths from surface text, preserving occurrence order. */
 export declare function extractFilePaths(texts: readonly string[], cwd: string): string[];
-/** Check whether a local file fits the accessory review surface's limits. */
+/** Check whether a local file fits the review surface's limits. */
 export declare function checkReviewableFile(abs: string): {
     ok: true;
 } | {

package/dist/{clients/attach → core/human}/visible-paths.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve } from 'node:path';
+import { documentLines } from '../document-lines.js';
 const MAX_CANDIDATES = 50;
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 const MAX_FILE_LINES = 5000;
@@ -45,7 +46,7 @@ export function extractFilePaths(texts, cwd) {
     }
     return found;
 }
-/** Check whether a local file fits the accessory review surface's limits. */
+/** Check whether a local file fits the review surface's limits. */
 export function checkReviewableFile(abs) {
     let size;
     try {
@@ -69,7 +70,7 @@ export function checkReviewableFile(abs) {
     if (content.includes('\uFFFD') || content.includes('\0')) {
         return { ok: false, reason: 'file is not UTF-8 text' };
     }
-    if (content.split('\n').length > MAX_FILE_LINES) {
+    if (documentLines(content).length > MAX_FILE_LINES) {
         return { ok: false, reason: 'file is too long to review (5,000 line limit)' };
     }
     return { ok: true };

package/dist/core/inspector/chrome.d.ts

@@ -0,0 +1,6 @@
+import type { ChromeState } from './contract.js';
+export type ChipState = 'working' | 'blocked' | 'attention' | 'ready' | 'idle';
+/** Derive the Inspector state chip from its current host signals. */
+export declare function deriveState(c: ChromeState): ChipState;
+/** A fresh Inspector chrome record. */
+export declare function initialChrome(): ChromeState;

package/dist/core/inspector/chrome.js

@@ -0,0 +1,14 @@
+/** Derive the Inspector state chip from its current host signals. */
+export function deriveState(c) {
+    if (c.busy)
+        return 'working';
+    if (c.banner?.level === 'error')
+        return 'blocked';
+    if (c.banner?.level === 'action')
+        return 'attention';
+    return c.loaded ? 'ready' : 'idle';
+}
+/** A fresh Inspector chrome record. */
+export function initialChrome() {
+    return { status: null, banner: null, subtitle: null, mode: null, busy: false, loaded: false, lastRefresh: 0 };
+}

package/dist/core/inspector/contract.d.ts

@@ -0,0 +1,105 @@
+import type { Draw, Rect } from '../tui/draw.js';
+import type { BindingId } from '../keybindings/index.js';
+export type BannerLevel = 'info' | 'action' | 'error';
+export interface Banner {
+    msg: string;
+    level: BannerLevel;
+}
+export interface DumpContext {
+    banner: Banner | null;
+}
+export interface HostSignals {
+    setStatus(msg: string | null): void;
+    setBanner(msg: string, level: BannerLevel): void;
+    clearBanner(): void;
+    setSubtitle(subtitle: string | null): void;
+    setMode(mode: string | null): void;
+    quit(): void;
+}
+export interface ChromeState {
+    status: string | null;
+    banner: Banner | null;
+    subtitle: string | null;
+    mode: string | null;
+    busy: boolean;
+    loaded: boolean;
+    lastRefresh: number;
+}
+export interface SourceRequest {
+    kind: 'exec';
+    bin: string;
+    args: string[];
+    cwd?: string;
+    stdin?: string;
+}
+export interface RawResponse {
+    ok: boolean;
+    exitCode?: number;
+    stdout: string;
+    stderr: string;
+}
+export interface SourceError {
+    kind: string;
+    display: {
+        headline: string;
+        explanation: string;
+        nextStep: string;
+        level: BannerLevel;
+        blocking: boolean;
+    };
+}
+export type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: SourceError;
+};
+export interface Source<T, A = void> {
+    id: string;
+    request(args: A): SourceRequest;
+    parse(raw: RawResponse): Result<T>;
+}
+export interface Command<T, A = void> {
+    id: string;
+    request(args: A): SourceRequest;
+    parse(raw: RawResponse): Result<T>;
+}
+export interface IntentCtx<S> {
+    readonly state: S;
+    set(next: S | ((previous: S) => S)): void;
+    resolve<T, A>(source: Source<T, A>, args?: A): Promise<Result<T>>;
+    execute<T, A>(command: Command<T, A>, args?: A): Promise<Result<T>>;
+    signal: HostSignals;
+    dispatch(intent: string, payload?: unknown): Promise<void>;
+}
+export type Intent<S, P = void> = (ctx: IntentCtx<S>, payload: P) => void | Promise<void>;
+export interface InspectorCore<S> {
+    manifest: {
+        title: string;
+        subtitle?: string;
+        refreshMs?: number;
+    };
+    init(options: Readonly<Record<string, string>>): S;
+    intents: Record<string, Intent<S, any>>;
+}
+export interface KeyHint {
+    keys: string;
+    label: string;
+}
+export interface InspectorKeyBinding<S> {
+    bindingId: BindingId;
+    intent: string;
+    payload?: (state: S) => unknown;
+    when?: (state: S) => boolean;
+    hint?: {
+        label: string;
+    };
+}
+export interface InspectorTui<S> {
+    render(state: S, draw: Draw, content: Rect): void;
+    keymap: InspectorKeyBinding<S>[];
+}
+export interface InspectorText<S> {
+    dump(state: S, context?: DumpContext): string;
+}

package/dist/core/inspector/contract.js

@@ -0,0 +1 @@
+export {};

package/dist/core/inspector/core.d.ts

@@ -1,9 +1,8 @@
 import type { CronDTO } from '../../api/dto/crons.js';
-import type { SourceError, ViewCore } from '../view/contract.js';
+import type { InspectorCore, SourceError } from './contract.js';
 import { scheduledItems, type BashJobRow, type InspectorSection } from './model.js';
-/** What a `y` confirmation will act on. Both sections arm cancellation the same
- *  way, so the pending action carries its own kind rather than the view guessing
- *  from whichever section happens to be open when the key lands. */
+/** What a `y` confirmation will act on. The pending action carries its own kind
+ *  so a section change cannot change the armed operation. */
 export type PendingAction = {
     kind: 'cron' | 'job';
     id: string;
@@ -33,6 +32,6 @@ export interface InspectorState {
     pendingCancel: PendingAction | null;
     scroll: Record<InspectorSection, number>;
 }
-export declare const inspectorCore: ViewCore<InspectorState>;
+export declare const inspectorCore: InspectorCore<InspectorState>;
 export declare function selectedJob(state: InspectorState): BashJobRow | undefined;
 export { scheduledItems };

package/dist/core/inspector/core.js

@@ -40,7 +40,7 @@ const scheduleSource = {
 const LOG_TAIL_LINES = 14;
 /** Live background bash jobs for the inspected node. Non-blocking, exactly like
  *  the schedule: a node with no jobs dir (or a remote target) degrades this one
- *  section, never the whole view. */
+ *  section, never the whole Inspector. */
 const jobsSource = {
     id: 'jobs',
     request: (target) => ({ kind: 'exec', bin: 'crtr', args: ['--json', 'node', 'bash', 'list', '--node', target, '--tail', String(LOG_TAIL_LINES)] }),
@@ -119,7 +119,7 @@ function reconcile(state, next) {
     return { ...state, schedule: { data: next, error: null, fetchedAt: Date.now() }, selectedCronId: replacement?.cron.cron_id ?? null, expanded: false, pendingCancel: null };
 }
 export const inspectorCore = {
-    manifest: { id: 'inspector', title: 'Inspector', description: 'Node overview, scheduled crons, and live background bash jobs', refreshMs: 5000 },
+    manifest: { title: 'Inspector', refreshMs: 5000 },
     init(options) {
         return {
             target: options['target'] ?? '', section: section(options['section']),
@@ -129,15 +129,13 @@ export const inspectorCore = {
             scroll: { overview: 0, schedule: 0, jobs: 0, raw: 0 },
         };
     },
-    sources: { dossier: dossierSource, schedule: scheduleSource, jobs: jobsSource },
-    commands: { cancel: cancelCommand, killJob: killJobCommand, openLog: openLogCommand },
     intents: {
         async refresh(ctx) {
             ctx.signal.setStatus('Refreshing…');
             let note;
             // All three reads are independent subprocesses, so they run TOGETHER: the
             // host drops keystrokes while an intent is in flight, and the auto-refresh
-            // fires every 5s — resolving them in series would make the view feel deaf.
+            // fires every 5s — resolving them in series would make the Inspector feel deaf.
             const [dossier, schedule, jobs] = await Promise.all([
                 ctx.resolve(dossierSource, ctx.state.target),
                 ctx.resolve(scheduleSource, ctx.state.target),

package/dist/core/inspector/host.d.ts

@@ -0,0 +1,46 @@
+import { type Draw, type Rect, type Size } from '../tui/draw.js';
+import type { InspectorCore, InspectorTui, InspectorText, InspectorKeyBinding, KeyHint, BannerLevel } from './contract.js';
+import { type BindingId, type BindingResolution, type RawTerminalInput } from '../keybindings/index.js';
+export interface RunInspectorOptions {
+    options?: Record<string, string>;
+}
+/** The host-tracked chrome state. `banner` + `busy` + `loaded` derive the title
+ *  state chip; `tick` advances the spinner under the busy-tick repaint. */
+export interface Chrome {
+    status: string | null;
+    banner: {
+        msg: string;
+        level: BannerLevel;
+    } | null;
+    busy: boolean;
+    loaded: boolean;
+    lastRefresh: number;
+    tick: number;
+    subtitle: string | null;
+    mode: string | null;
+}
+/** The Inspector title and effective footer key hints. */
+export interface InspectorChromeManifest {
+    title: string;
+    subtitle?: string;
+    keymap?: KeyHint[];
+}
+/** Draw the host chrome into `draw` and return the content Rect for the view.
+ *  Three zones: title row (state rail + title/subtitle + state chip + liveness),
+ *  a hairline, and a footer (status left, keymap right) with a severity banner
+ *  on the row above it when set. */
+declare function drawInspectorChrome(draw: Draw, size: Size, manifest: InspectorChromeManifest, c: Chrome, now?: number): Rect;
+export { drawInspectorChrome };
+/** Decode terminal bytes into the shared keybinding catalog's input shape. */
+export declare function parseInspectorInput(data: Buffer, bindings?: BindingResolution<BindingId>): RawTerminalInput;
+/** Resolve footer hints from the Inspector's current mode and user bindings. */
+export declare function resolveInspectorKeyHints<S>(keymap: InspectorKeyBinding<S>[], bindings: BindingResolution<BindingId>, state: S): KeyHint[];
+/** Match the first active Inspector action claimed by the input. */
+export declare function matchInspectorBinding<S>(keymap: InspectorKeyBinding<S>[], bindings: BindingResolution<BindingId>, state: S, raw: RawTerminalInput): {
+    intent: string;
+    payload: unknown;
+} | null;
+/** Match the Inspector host's exit action through the catalog snapshot. */
+export declare function matchesInspectorHostBinding(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): boolean;
+/** Host the Inspector until it quits, or emit its static text snapshot. */
+export declare function runInspector<S>(core: InspectorCore<S>, tui: InspectorTui<S>, text: InspectorText<S>, opts?: RunInspectorOptions): Promise<void>;