@north-light/crouter 0.3.170 → 0.3.172

package/dist/clients/conversation/conversation.d.ts

@@ -0,0 +1,65 @@
+import { type TUI } from '@earendil-works/pi-tui';
+import type { CanvasSource } from '../../core/canvas/source.js';
+import { type SessionState } from '../../core/session-model/session-state.js';
+import { ChatView } from '../attach/render/chat-view.js';
+import { type TranscriptViewport } from '../attach/render/viewport.js';
+export type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'dormant' | 'finished' | 'gone';
+export interface SurfaceConversationOptions {
+    nodeId: string;
+    /** Required by ChatView; this unit never drives the TUI directly. */
+    tui: TUI;
+    /** The reconnect supervisor's give-up read. */
+    canvasSource: CanvasSource;
+    /** The owning region's only repaint channel. */
+    onDirty(): void;
+    onConnection(state: ConnectionState): void;
+    /** One new transcript message, so an unread tally counts arrivals rather than
+     *  repaints (a streaming spinner invalidates continuously). */
+    onMessage(): void;
+    /** Request the review owner's canonical reopen operation when the attached broker is dormant. */
+    reopenDormantCompanion(): Promise<void>;
+    /** Region-scoped feedback, never a viewer-host notice. */
+    notice(text: string): void;
+}
+/**
+ * A reusable local controller connection for a companion node. It deliberately
+ * attaches to the companion broker. Its owner supplies the canonical review
+ * reopen operation for dormant input; this unit never revives a node itself.
+ */
+export declare class SurfaceConversation {
+    readonly chatView: ChatView;
+    readonly viewport: TranscriptViewport;
+    private readonly nodeId;
+    private readonly canvasSource;
+    private readonly onDirty;
+    private readonly onConnection;
+    private readonly onMessage;
+    private readonly notice;
+    private readonly reopenDormantCompanion;
+    private readonly socket;
+    private readonly role;
+    private session;
+    private state;
+    private tornDown;
+    private opened;
+    private reconnect;
+    private readonly queuedInputs;
+    private reopeningDormantCompanion;
+    constructor(opts: SurfaceConversationOptions);
+    connection(): ConnectionState;
+    sessionState(): SessionState;
+    /** Connect only to the already-running companion broker. */
+    open(): Promise<void>;
+    /** Submit through the one shared classifier; this unit has no slash chrome. */
+    submit(text: string): void;
+    abort(): void;
+    /** Stop redial first, then detach this client without changing node lifecycle. */
+    close(): void;
+    private installReconnect;
+    private send;
+    private reopenDormant;
+    private liveInputFrame;
+    private flushQueuedInputs;
+    private setConnection;
+    private dirty;
+}

package/dist/clients/conversation/conversation.js

@@ -0,0 +1,318 @@
+// conversation/conversation.ts — a headless broker-backed companion conversation.
+//
+// The review daemon owns companion liveness. This unit only connects to the
+// existing view.sock and projects its broker frames into reusable chat state.
+import { randomUUID } from 'node:crypto';
+import { Container } from '@earendil-works/pi-tui';
+import { BrokerClient } from '../../core/broker-client/index.js';
+import { initialSessionState, reduce } from '../../core/session-model/session-state.js';
+import { ChatView } from '../attach/render/chat-view.js';
+import { createTranscriptViewport } from '../attach/render/viewport.js';
+import { resolveHelloRole } from '../attach/session/connection.js';
+import { createReconnect } from '../attach/session/reconnect.js';
+import { classifySubmit } from './submit.js';
+import { createCompanionFrameHandler } from './frames.js';
+/**
+ * A reusable local controller connection for a companion node. It deliberately
+ * attaches to the companion broker. Its owner supplies the canonical review
+ * reopen operation for dormant input; this unit never revives a node itself.
+ */
+export class SurfaceConversation {
+    chatView;
+    viewport;
+    nodeId;
+    canvasSource;
+    onDirty;
+    onConnection;
+    onMessage;
+    notice;
+    reopenDormantCompanion;
+    socket;
+    role = resolveHelloRole(false, false);
+    session = initialSessionState(this.role);
+    state = 'connecting';
+    tornDown = false;
+    opened = false;
+    reconnect;
+    queuedInputs = [];
+    reopeningDormantCompanion = false;
+    constructor(opts) {
+        this.nodeId = opts.nodeId;
+        this.canvasSource = opts.canvasSource;
+        this.onDirty = opts.onDirty;
+        this.onConnection = opts.onConnection;
+        this.onMessage = opts.onMessage;
+        this.notice = opts.notice;
+        this.reopenDormantCompanion = opts.reopenDormantCompanion;
+        this.socket = new BrokerClient(opts.nodeId);
+        const chatContainer = new Container();
+        // ChatView and its self-updating children only receive an invalidation
+        // facade. Their requestRender calls return through the owning region rather
+        // than bypassing it to repaint the outer attach TUI directly.
+        const chatTui = {
+            requestRender: () => this.dirty(),
+            terminal: opts.tui.terminal,
+        };
+        this.chatView = new ChatView(chatTui, chatContainer, {
+            onActivityChange: () => this.dirty(),
+        });
+        this.viewport = createTranscriptViewport(this.chatView.transcriptSource());
+    }
+    connection() {
+        return this.state;
+    }
+    sessionState() {
+        return this.session;
+    }
+    /** Connect only to the already-running companion broker. */
+    open() {
+        if (this.opened)
+            return Promise.resolve();
+        if (this.tornDown)
+            return Promise.reject(new Error('surface conversation is closed'));
+        this.opened = true;
+        this.setConnection('connecting');
+        return new Promise((resolve, reject) => {
+            const onConnect = () => {
+                cleanup();
+                this.installReconnect();
+                this.reconnect?.sendHello();
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                this.opened = false;
+                this.notice(`couldn't connect to companion: ${error.message}`);
+                this.dirty();
+                reject(error);
+            };
+            const cleanup = () => {
+                this.socket.off('connect', onConnect);
+                this.socket.off('error', onError);
+            };
+            this.socket.once('connect', onConnect);
+            this.socket.once('error', onError);
+            this.socket.connect();
+        });
+    }
+    /** Submit through the one shared classifier; this unit has no slash chrome. */
+    submit(text) {
+        if (this.tornDown || this.state === 'finished' || this.state === 'gone') {
+            this.notice('companion is no longer available');
+            this.dirty();
+            return;
+        }
+        if (this.state === 'connecting' || this.state === 'reconnecting') {
+            const frame = this.liveInputFrame(text);
+            if (frame === undefined)
+                return;
+            this.queuedInputs.push(frame);
+            this.notice('companion is reconnecting — input queued');
+            this.dirty();
+            return;
+        }
+        const classification = classifySubmit(text, {
+            isDormant: this.reconnect?.isDormant() === true,
+            canWakeDormant: true,
+            isStreaming: this.session.engine?.isStreaming === true,
+        });
+        switch (classification.kind) {
+            case 'empty':
+                return;
+            case 'dormant':
+                void this.reopenDormant({ type: 'prompt', text: classification.text });
+                return;
+            case 'bash':
+                this.send({ type: 'bash', command: classification.command, excludeFromContext: classification.excludeFromContext });
+                return;
+            case 'steer':
+                this.send({ type: 'steer', text: classification.text });
+                return;
+            case 'slash':
+                // This column has no slash dispatcher. A slash is ordinary companion
+                // input, so a dormant broker still needs the review-owned reopen path.
+                if (this.reconnect?.isDormant() === true) {
+                    void this.reopenDormant({ type: 'prompt', text });
+                    return;
+                }
+                this.send({ type: 'prompt', text });
+                return;
+            case 'prompt':
+                this.send({ type: 'prompt', text });
+                return;
+        }
+    }
+    abort() {
+        this.send({ type: 'abort' });
+    }
+    /** Stop redial first, then detach this client without changing node lifecycle. */
+    close() {
+        if (this.tornDown)
+            return;
+        this.tornDown = true;
+        this.reconnect?.stop();
+        try {
+            this.socket.send({ type: 'bye' });
+        }
+        catch {
+            // BrokerClient send is best-effort; a close race is ordinary teardown.
+        }
+        this.socket.close();
+        try {
+            this.chatView.dispose();
+        }
+        catch {
+            // A stale pi component must not block host cleanup.
+        }
+    }
+    installReconnect() {
+        if (this.reconnect !== undefined)
+            return;
+        const nodeDone = () => this.setConnection('finished');
+        const handleFrame = createCompanionFrameHandler({
+            foldState: (frame) => {
+                this.session = reduce(this.session, frame);
+                this.dirty();
+            },
+            chat: {
+                applySnapshot: (snapshot) => {
+                    const applied = this.chatView.applySnapshot(snapshot);
+                    this.dirty();
+                    return applied;
+                },
+                handleEvent: (event) => {
+                    this.chatView.handleEvent(event);
+                    if (event.type === 'message_start')
+                        this.onMessage();
+                    this.dirty();
+                },
+                bashStart: (command, excludeFromContext) => {
+                    this.chatView.bashStart(command, excludeFromContext);
+                    this.dirty();
+                },
+                bashOutput: (chunk) => {
+                    this.chatView.bashOutput(chunk);
+                    this.dirty();
+                },
+                bashEnd: (frame) => {
+                    this.chatView.bashEnd(frame);
+                    this.dirty();
+                },
+                applyToolGroupSummary: (key, summary) => {
+                    this.chatView.applyToolGroupSummary(key, summary);
+                    this.dirty();
+                },
+            },
+            setConnection: () => {
+                this.setConnection('connected');
+                this.flushQueuedInputs();
+            },
+            notice: (text) => {
+                this.notice(text);
+                this.dirty();
+            },
+            declineDialog: (request) => this.socket.send({ type: 'extension_ui_response', id: request.id, cancelled: true }),
+            onNodeDone: nodeDone,
+        });
+        this.reconnect = createReconnect({ nodeId: this.nodeId, socket: this.socket, canvasSource: this.canvasSource }, {
+            role: this.role,
+            clientId: randomUUID(),
+            onFrame: handleFrame,
+            setNotice: (text) => {
+                if (text)
+                    this.setConnection('reconnecting');
+                this.notice(text);
+                this.dirty();
+            },
+            isTornDown: () => this.tornDown,
+            teardown: (reason) => {
+                if (reason === 'node-done')
+                    nodeDone();
+                else
+                    this.setConnection('gone');
+            },
+            onEnterDormancy: () => {
+                this.chatView.settleRun();
+                this.session = this.session.engine === undefined
+                    ? this.session
+                    : { ...this.session, engine: { ...this.session.engine, isStreaming: false } };
+                this.setConnection('dormant');
+            },
+        });
+        this.reconnect.install();
+    }
+    send(frame) {
+        if (this.tornDown || this.state === 'finished' || this.state === 'gone') {
+            this.notice('companion is no longer available');
+            this.dirty();
+            return;
+        }
+        if (this.state === 'connecting' || this.state === 'reconnecting') {
+            this.notice('companion is reconnecting — input was not sent');
+            this.dirty();
+            return;
+        }
+        this.socket.send(frame);
+    }
+    async reopenDormant(frame) {
+        this.queuedInputs.push(frame);
+        if (this.reopeningDormantCompanion) {
+            this.notice('↻ waking companion — input queued');
+            this.dirty();
+            return;
+        }
+        this.reopeningDormantCompanion = true;
+        this.setConnection('reconnecting');
+        try {
+            await this.reopenDormantCompanion();
+            this.notice('↻ waking companion…');
+        }
+        catch (error) {
+            this.setConnection('dormant');
+            this.notice(`couldn't reopen companion; input is queued: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            this.reopeningDormantCompanion = false;
+            this.flushQueuedInputs();
+            this.dirty();
+        }
+    }
+    liveInputFrame(text) {
+        const classification = classifySubmit(text, {
+            isDormant: false,
+            canWakeDormant: false,
+            isStreaming: this.session.engine?.isStreaming === true,
+        });
+        switch (classification.kind) {
+            case 'empty':
+                return undefined;
+            case 'bash':
+                return { type: 'bash', command: classification.command, excludeFromContext: classification.excludeFromContext };
+            case 'steer':
+                return { type: 'steer', text: classification.text };
+            case 'slash':
+            case 'prompt':
+                return { type: 'prompt', text };
+            case 'dormant':
+                throw new Error('live companion input cannot be dormant');
+        }
+    }
+    flushQueuedInputs() {
+        if (this.tornDown || this.reopeningDormantCompanion || this.state !== 'connected')
+            return;
+        for (const frame of this.queuedInputs.splice(0)) {
+            this.socket.send(frame);
+        }
+    }
+    setConnection(state) {
+        if (this.state === state)
+            return;
+        this.state = state;
+        this.onConnection(state);
+        this.dirty();
+    }
+    dirty() {
+        if (!this.tornDown)
+            this.onDirty();
+    }
+}

package/dist/clients/conversation/frames.d.ts

@@ -0,0 +1,30 @@
+import type { AgentSessionEvent } from '@earendil-works/pi-coding-agent';
+import type { BrokerToClient, RpcExtensionUIRequest } from '../../core/runtime/broker-protocol.js';
+import type { ToolGroupSummary } from '../../shared/tool-groups.js';
+export interface CompanionFrameEffects {
+    /** Fold every broker fact through the shared session reducer before local effects. */
+    foldState: (frame: BrokerToClient) => void;
+    /** The only transcript writes a companion conversation performs. */
+    chat: {
+        applySnapshot: (snapshot: Extract<BrokerToClient, {
+            type: 'welcome';
+        }>['snapshot']) => Promise<void> | void;
+        handleEvent: (event: AgentSessionEvent) => void;
+        bashStart: (command: string, excludeFromContext?: boolean) => void;
+        bashOutput: (chunk: string) => void;
+        bashEnd: (frame: Extract<BrokerToClient, {
+            type: 'bash_end';
+        }>) => void;
+        applyToolGroupSummary: (key: string, summary: ToolGroupSummary) => void;
+    };
+    /** The welcome handshake established a live broker connection. */
+    setConnection: () => void;
+    /** A region-scoped transient. */
+    notice: (text: string) => void;
+    /** Decline a blocking extension dialog rather than mounting another overlay host. */
+    declineDialog: (request: RpcExtensionUIRequest) => void;
+    /** The reconnect supervisor establishes terminal node completion. */
+    onNodeDone: () => void;
+}
+/** Build the companion's deliberately small broker-frame handler. */
+export declare function createCompanionFrameHandler(fx: CompanionFrameEffects): (frame: BrokerToClient) => void;

package/dist/clients/conversation/frames.js

@@ -0,0 +1,52 @@
+// conversation/frames.ts — broker-frame effects for a companion conversation.
+//
+// This is intentionally narrower than attach/session/frames.ts. A companion
+// column owns transcript state and connection presentation, not viewer chrome.
+function isBlockingDialog(request) {
+    return request.method === 'select' || request.method === 'confirm' || request.method === 'input' || request.method === 'editor';
+}
+/** Build the companion's deliberately small broker-frame handler. */
+export function createCompanionFrameHandler(fx) {
+    return (frame) => {
+        fx.foldState(frame);
+        switch (frame.type) {
+            case 'welcome':
+                void fx.chat.applySnapshot(frame.snapshot);
+                fx.setConnection();
+                if (frame.pending_dialog !== null && frame.pending_dialog !== undefined && isBlockingDialog(frame.pending_dialog)) {
+                    fx.declineDialog(frame.pending_dialog);
+                    fx.notice('companion asked for a dialog — open its own attach view');
+                }
+                return;
+            case 'tool_group_summary':
+                fx.chat.applyToolGroupSummary(frame.key, frame.summary);
+                return;
+            case 'error':
+                fx.notice(frame.code === 'read_only' ? 'read-only' : `error: ${frame.message}`);
+                return;
+            case 'ack':
+                if (!frame.ok)
+                    fx.notice(`command failed: ${frame.for}${frame.detail ? ` — ${frame.detail}` : ''}`);
+                return;
+            case 'extension_ui_request':
+                if (isBlockingDialog(frame)) {
+                    fx.declineDialog(frame);
+                    fx.notice('companion asked for a dialog — open its own attach view');
+                }
+                return;
+            case 'extension_ui_dismiss':
+                return;
+            case 'bash_start':
+                fx.chat.bashStart(frame.command, frame.excludeFromContext);
+                return;
+            case 'bash_output':
+                fx.chat.bashOutput(frame.chunk);
+                return;
+            case 'bash_end':
+                fx.chat.bashEnd(frame);
+                return;
+            default:
+                fx.chat.handleEvent(frame);
+        }
+    };
+}

package/dist/clients/conversation/region.d.ts

@@ -0,0 +1,51 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import type { CanvasSource } from '../../core/canvas/source.js';
+import type { SurfaceRegion } from '../surfaces/region.js';
+export interface CompanionRegionOptions {
+    companionNodeId: string;
+    tui: TUI;
+    canvasSource: CanvasSource;
+    reopenDormantCompanion(): Promise<void>;
+    onRequestClose(): void;
+}
+/**
+ * A companion conversation region for a composed review. Renders connection
+ * state, editor, and transcript in a bounded viewport. The only repaint channel
+ * is onDirty; geometry is always pushed.
+ */
+export declare class CompanionRegion implements SurfaceRegion {
+    private readonly editor;
+    private readonly conversation;
+    private cols;
+    private rows;
+    private focused;
+    private isDirty;
+    private renderCache;
+    private unreadCount;
+    private connectionState;
+    private noticeText;
+    private onDirtyCallback?;
+    constructor(opts: CompanionRegionOptions);
+    setViewport(cols: number, rows: number): void;
+    render(): string[];
+    handleInput(data: string): boolean;
+    handleWheel(direction: 'up' | 'down', lines: number): boolean;
+    setFocused(value: boolean): void;
+    summary(): string;
+    onDirty(fn: () => void): void;
+    close(): void;
+    /** Open the connection to the companion broker. */
+    open(): Promise<void>;
+    /** Submit text to the companion. */
+    submit(text: string): void;
+    private renderStateLine;
+    private fitLine;
+    private padLine;
+    private stripMarkers;
+    private onConnectionChange;
+    private showNotice;
+    private isHidden;
+    /** One arriving message while the composition gives this region no rectangle. */
+    private countUnread;
+    private dirty;
+}