catui-agent 1.0.0-beta.0

package/dist/core/lib/tui/src/tui.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Minimal TUI implementation with differential rendering
+ */
+/**
+ * [WHO]: Component, Focusable, isFocusable, CURSOR_MARKER, visibleWidth
+ * [FROM]: Depends on node:fs, node:os, node:path, ./keys.js, ./terminal-image.js
+ * [TO]: Consumed by core/lib/tui/src/index.ts
+ * [HERE]: core/lib/tui/src/tui.ts -
+ */
+import type { Terminal } from "./terminal.js";
+import { visibleWidth } from "./utils.js";
+/**
+ * Component interface - all components must implement this
+ */
+export interface Component {
+    /**
+     * Render the component to lines for the given viewport width
+     * @param width - Current viewport width
+     * @returns Array of strings, each representing a line
+     */
+    render(width: number): string[];
+    /**
+     * Optional handler for keyboard input when component has focus
+     */
+    handleInput?(data: string): void;
+    /**
+     * If true, component receives key release events (Kitty protocol).
+     * Default is false - release events are filtered out.
+     */
+    wantsKeyRelease?: boolean;
+    /**
+     * Invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate(): void;
+}
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+/**
+ * Interface for components that can receive focus and display a hardware cursor.
+ * When focused, the component should emit CURSOR_MARKER at the cursor position
+ * in its render output. TUI will find this marker and position the hardware
+ * cursor there for proper IME candidate window positioning.
+ */
+export interface Focusable {
+    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
+    focused: boolean;
+}
+/** Type guard to check if a component implements Focusable */
+export declare function isFocusable(component: Component | null): component is Component & Focusable;
+/**
+ * Cursor position marker - APC (Application Program Command) sequence.
+ * This is a zero-width escape sequence that terminals ignore.
+ * Components emit this at the cursor position when focused.
+ * TUI finds and strips this marker, then positions the hardware cursor there.
+ */
+export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
+export { visibleWidth };
+/**
+ * Anchor position for overlays
+ */
+export type OverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+/**
+ * Margin configuration for overlays
+ */
+export interface OverlayMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Value that can be absolute (number) or percentage (string like "50%") */
+export type SizeValue = number | `${number}%`;
+/**
+ * Options for overlay positioning and sizing.
+ * Values can be absolute numbers or percentage strings (e.g., "50%").
+ */
+export interface OverlayOptions {
+    /** Width in columns, or percentage of terminal width (e.g., "50%") */
+    width?: SizeValue;
+    /** Minimum width in columns */
+    minWidth?: number;
+    /** Maximum height in rows, or percentage of terminal height (e.g., "50%") */
+    maxHeight?: SizeValue;
+    /** Anchor point for positioning (default: 'center') */
+    anchor?: OverlayAnchor;
+    /** Horizontal offset from anchor position (positive = right) */
+    offsetX?: number;
+    /** Vertical offset from anchor position (positive = down) */
+    offsetY?: number;
+    /** Row position: absolute number, or percentage (e.g., "25%" = 25% from top) */
+    row?: SizeValue;
+    /** Column position: absolute number, or percentage (e.g., "50%" = centered horizontally) */
+    col?: SizeValue;
+    /** Margin from terminal edges. Number applies to all sides. */
+    margin?: OverlayMargin | number;
+    /**
+     * Control overlay visibility based on terminal dimensions.
+     * If provided, overlay is only rendered when this returns true.
+     * Called each render cycle with current terminal dimensions.
+     */
+    visible?: (termWidth: number, termHeight: number) => boolean;
+}
+/**
+ * Handle returned by showOverlay for controlling the overlay
+ */
+export interface OverlayHandle {
+    /** Permanently remove the overlay (cannot be shown again) */
+    hide(): void;
+    /** Temporarily hide or show the overlay */
+    setHidden(hidden: boolean): void;
+    /** Check if overlay is temporarily hidden */
+    isHidden(): boolean;
+}
+/**
+ * Container - a component that contains other components
+ */
+export declare class Container implements Component {
+    children: Component[];
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    terminal: Terminal;
+    private previousLines;
+    private previousWidth;
+    private focusedComponent;
+    private inputListeners;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    private renderRequested;
+    private renderWaiters;
+    private cursorRow;
+    private hardwareCursorRow;
+    private inputBuffer;
+    private cellSizeQueryPending;
+    private showHardwareCursor;
+    private clearOnShrink;
+    private maxLinesRendered;
+    private previousViewportTop;
+    private fullRedrawCount;
+    private stopped;
+    private synchronizedOutputEnabled;
+    private overlayStack;
+    private debugLog;
+    constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    get fullRedraws(): number;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    /**
+     * Set whether to trigger full re-render when content shrinks.
+     * When true (default), empty rows are cleared when content shrinks.
+     * When false, empty rows remain (reduces redraws on slower terminals).
+     */
+    setClearOnShrink(enabled: boolean): void;
+    private wrapRenderBuffer;
+    setFocus(component: Component | null): void;
+    /**
+     * Show an overlay component with configurable positioning and sizing.
+     * Returns a handle to control the overlay's visibility.
+     */
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    /** Hide the topmost overlay and restore previous focus. */
+    hideOverlay(): void;
+    /** Check if there are any visible overlays */
+    hasOverlay(): boolean;
+    /** Check if an overlay entry is currently visible */
+    private isOverlayVisible;
+    /** Find the topmost visible overlay, if any */
+    private getTopmostVisibleOverlay;
+    invalidate(): void;
+    start(): void;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    private queryCellSize;
+    stop(): void;
+    requestRender(force?: boolean): void;
+    awaitRender(): Promise<void>;
+    private handleInput;
+    private parseCellSizeResponse;
+    /**
+     * Resolve overlay layout from options.
+     * Returns { width, row, col, maxHeight } for rendering.
+     */
+    private resolveOverlayLayout;
+    private resolveAnchorRow;
+    private resolveAnchorCol;
+    /** Composite all overlays into content lines (in stack order, later = on top). */
+    private compositeOverlays;
+    private static readonly SEGMENT_RESET;
+    private applyLineResets;
+    /** Splice overlay content into a base line at a specific column. Single-pass optimized. */
+    private compositeLineAt;
+    /**
+     * Find and extract cursor position from rendered lines.
+     * Searches for CURSOR_MARKER, calculates its position, and strips it from the output.
+     * Only scans the bottom terminal height lines (visible viewport).
+     * @param lines - Rendered lines to search
+     * @param height - Terminal height (visible viewport size)
+     * @returns Cursor position { row, col } or null if no marker found
+     */
+    private extractCursorPosition;
+    private doRender;
+    /**
+     * Position the hardware cursor for IME candidate window.
+     * @param cursorPos The cursor position extracted from rendered output, or null
+     * @param totalLines Total number of rendered lines
+     */
+    private positionHardwareCursor;
+}

package/dist/core/lib/tui/src/tui.js

@@ -0,0 +1,12 @@
+var W=Object.defineProperty;var b=(R,e)=>W(R,"name",{value:e,configurable:!0});import*as $ from"node:fs";import*as V from"node:os";import*as k from"node:path";import{isKeyRelease as N,matchesKey as K}from"./keys.js";import{getCapabilities as G,isImageLine as I,setCellDimensions as j}from"./terminal-image.js";import{extractSegments as J,sliceByColumn as P,sliceWithWidth as Y,visibleWidth as L}from"./utils.js";function _(R){return R!==null&&"focused"in R}b(_,"isFocusable");function Q(){if(process.env.CATUI_SYNC_OUTPUT==="0")return!1;if(process.env.CATUI_SYNC_OUTPUT==="1")return!0;const R=process.env.TERM_PROGRAM?.toLowerCase()||"";return!new Set(["warpterminal","waveterm"]).has(R)}b(Q,"shouldUseSynchronizedOutput");const F="\x1B_pi:c\x07";function q(R,e){if(R===void 0)return;if(typeof R=="number")return R;const t=R.match(/^(\d+(?:\.\d+)?)%$/);if(t)return Math.floor(e*parseFloat(t[1])/100)}b(q,"parseSizeValue");class X{static{b(this,"Container")}children=[];addChild(e){this.children.push(e)}removeChild(e){const t=this.children.indexOf(e);t!==-1&&this.children.splice(t,1)}clear(){this.children=[]}invalidate(){for(const e of this.children)e.invalidate?.()}render(e){const t=[];for(const i of this.children)t.push(...i.render(e));return t}}class D extends X{static{b(this,"TUI")}terminal;previousLines=[];previousWidth=0;focusedComponent=null;inputListeners=new Set;onDebug;renderRequested=!1;renderWaiters=[];cursorRow=0;hardwareCursorRow=0;inputBuffer="";cellSizeQueryPending=!1;showHardwareCursor=process.env.CATUI_HARDWARE_CURSOR==="1";clearOnShrink=process.env.CATUI_CLEAR_ON_SHRINK==="1";maxLinesRendered=0;previousViewportTop=0;fullRedrawCount=0;stopped=!1;synchronizedOutputEnabled=Q();overlayStack=[];debugLog(e){if(process.env.CATUI_DEBUG_RENDER!=="1")return;const t=k.join(V.homedir(),".catui","agent","catui-debug.log");$.appendFileSync(t,`[${new Date().toISOString()}] [tui] ${e}
+`)}constructor(e,t){super(),this.terminal=e,t!==void 0&&(this.showHardwareCursor=t)}get fullRedraws(){return this.fullRedrawCount}getShowHardwareCursor(){return this.showHardwareCursor}setShowHardwareCursor(e){this.showHardwareCursor!==e&&(this.showHardwareCursor=e,e||this.terminal.hideCursor(),this.requestRender())}getClearOnShrink(){return this.clearOnShrink}setClearOnShrink(e){this.clearOnShrink=e}wrapRenderBuffer(e){return this.synchronizedOutputEnabled?`\x1B[?2026h${e}\x1B[?2026l`:e}setFocus(e){_(this.focusedComponent)&&(this.focusedComponent.focused=!1),this.focusedComponent=e,_(e)&&(e.focused=!0)}showOverlay(e,t){const i={component:e,options:t,preFocus:this.focusedComponent,hidden:!1};return this.overlayStack.push(i),this.isOverlayVisible(i)&&this.setFocus(e),this.terminal.hideCursor(),this.requestRender(),{hide:b(()=>{const n=this.overlayStack.indexOf(i);if(n!==-1){if(this.overlayStack.splice(n,1),this.focusedComponent===e){const r=this.getTopmostVisibleOverlay();this.setFocus(r?.component??i.preFocus)}this.overlayStack.length===0&&this.terminal.hideCursor(),this.requestRender()}},"hide"),setHidden:b(n=>{if(i.hidden!==n){if(i.hidden=n,n){if(this.focusedComponent===e){const r=this.getTopmostVisibleOverlay();this.setFocus(r?.component??i.preFocus)}}else this.isOverlayVisible(i)&&this.setFocus(e);this.requestRender()}},"setHidden"),isHidden:b(()=>i.hidden,"isHidden")}}hideOverlay(){const e=this.overlayStack.pop();if(!e)return;const t=this.getTopmostVisibleOverlay();this.setFocus(t?.component??e.preFocus),this.overlayStack.length===0&&this.terminal.hideCursor(),this.requestRender()}hasOverlay(){return this.overlayStack.some(e=>this.isOverlayVisible(e))}isOverlayVisible(e){return e.hidden?!1:e.options?.visible?e.options.visible(this.terminal.columns,this.terminal.rows):!0}getTopmostVisibleOverlay(){for(let e=this.overlayStack.length-1;e>=0;e--)if(this.isOverlayVisible(this.overlayStack[e]))return this.overlayStack[e]}invalidate(){super.invalidate();for(const e of this.overlayStack)e.component.invalidate?.()}start(){this.stopped=!1,this.terminal.start(e=>this.handleInput(e),()=>this.requestRender()),this.terminal.hideCursor(),this.queryCellSize(),this.requestRender()}addInputListener(e){return this.inputListeners.add(e),()=>{this.inputListeners.delete(e)}}removeInputListener(e){this.inputListeners.delete(e)}queryCellSize(){G().images&&(this.cellSizeQueryPending=!0,this.terminal.write("\x1B[16t"))}stop(){if(this.stopped=!0,this.previousLines.length>0){const t=this.previousLines.length-this.hardwareCursorRow;t>0?this.terminal.write(`\x1B[${t}B`):t<0&&this.terminal.write(`\x1B[${-t}A`),this.terminal.write(`\r
+`)}this.terminal.showCursor(),this.terminal.stop()}requestRender(e=!1){e&&(this.previousLines=[],this.previousWidth=-1,this.cursorRow=0,this.hardwareCursorRow=0,this.maxLinesRendered=0,this.previousViewportTop=0),!this.renderRequested&&(this.renderRequested=!0,this.debugLog(`requestRender (force=${e})`),process.nextTick(()=>{const t=this.renderWaiters.splice(0);this.renderRequested=!1;try{this.doRender()}finally{for(const i of t)i()}}))}async awaitRender(){this.renderRequested&&await new Promise(e=>{this.renderWaiters.push(e)})}handleInput(e){if(this.inputListeners.size>0){let i=e;for(const n of this.inputListeners){const r=n(i);if(r?.consume)return;r?.data!==void 0&&(i=r.data)}if(i.length===0)return;e=i}if(this.cellSizeQueryPending){this.inputBuffer+=e;const i=this.parseCellSizeResponse();if(i.length===0)return;e=i}if(K(e,"shift+ctrl+d")&&this.onDebug){this.onDebug();return}const t=this.overlayStack.find(i=>i.component===this.focusedComponent);if(t&&!this.isOverlayVisible(t)){const i=this.getTopmostVisibleOverlay();i?this.setFocus(i.component):this.setFocus(t.preFocus)}if(this.focusedComponent?.handleInput){if(N(e)&&!this.focusedComponent.wantsKeyRelease)return;this.focusedComponent.handleInput(e),this.requestRender()}}parseCellSizeResponse(){const e=/\x1b\[6;(\d+);(\d+)t/,t=this.inputBuffer.match(e);if(t){const r=parseInt(t[1],10),l=parseInt(t[2],10);r>0&&l>0&&(j({widthPx:l,heightPx:r}),this.invalidate(),this.requestRender()),this.inputBuffer=this.inputBuffer.replace(e,""),this.cellSizeQueryPending=!1}if(/\x1b(\[6?;?[\d;]*)?$/.test(this.inputBuffer)){const r=this.inputBuffer[this.inputBuffer.length-1];if(!/[a-zA-Z~]/.test(r))return""}const n=this.inputBuffer;return this.inputBuffer="",this.cellSizeQueryPending=!1,n}resolveOverlayLayout(e,t,i,n){const r=e??{},l=typeof r.margin=="number"?{top:r.margin,right:r.margin,bottom:r.margin,left:r.margin}:r.margin??{},s=Math.max(0,l.top??0),w=Math.max(0,l.right??0),y=Math.max(0,l.bottom??0),u=Math.max(0,l.left??0),v=Math.max(1,i-u-w),m=Math.max(1,n-s-y);let h=q(r.width,i)??Math.min(80,v);r.minWidth!==void 0&&(h=Math.max(h,r.minWidth)),h=Math.max(1,Math.min(h,v));let c=q(r.maxHeight,n);c!==void 0&&(c=Math.max(1,Math.min(c,m)));const d=c!==void 0?Math.min(t,c):t;let p,x;if(r.row!==void 0)if(typeof r.row=="string"){const C=r.row.match(/^(\d+(?:\.\d+)?)%$/);if(C){const g=Math.max(0,m-d),M=parseFloat(C[1])/100;p=s+Math.floor(g*M)}else p=this.resolveAnchorRow("center",d,m,s)}else p=r.row;else{const C=r.anchor??"center";p=this.resolveAnchorRow(C,d,m,s)}if(r.col!==void 0)if(typeof r.col=="string"){const C=r.col.match(/^(\d+(?:\.\d+)?)%$/);if(C){const g=Math.max(0,v-h),M=parseFloat(C[1])/100;x=u+Math.floor(g*M)}else x=this.resolveAnchorCol("center",h,v,u)}else x=r.col;else{const C=r.anchor??"center";x=this.resolveAnchorCol(C,h,v,u)}return r.offsetY!==void 0&&(p+=r.offsetY),r.offsetX!==void 0&&(x+=r.offsetX),p=Math.max(s,Math.min(p,n-y-d)),x=Math.max(u,Math.min(x,i-w-h)),{width:h,row:p,col:x,maxHeight:c}}resolveAnchorRow(e,t,i,n){switch(e){case"top-left":case"top-center":case"top-right":return n;case"bottom-left":case"bottom-center":case"bottom-right":return n+i-t;case"left-center":case"center":case"right-center":return n+Math.floor((i-t)/2)}}resolveAnchorCol(e,t,i,n){switch(e){case"top-left":case"left-center":case"bottom-left":return n;case"top-right":case"right-center":case"bottom-right":return n+i-t;case"top-center":case"center":case"bottom-center":return n+Math.floor((i-t)/2)}}compositeOverlays(e,t,i){if(this.overlayStack.length===0)return e;const n=[...e],r=[];let l=n.length;for(const u of this.overlayStack){if(!this.isOverlayVisible(u))continue;const{component:v,options:m}=u,{width:h,maxHeight:c}=this.resolveOverlayLayout(m,0,t,i);let d=v.render(h);c!==void 0&&d.length>c&&(d=d.slice(0,c));const{row:p,col:x}=this.resolveOverlayLayout(m,d.length,t,i);r.push({overlayLines:d,row:p,col:x,w:h}),l=Math.max(l,p+d.length)}const s=Math.max(this.maxLinesRendered,l);for(;n.length<s;)n.push("");const w=Math.max(0,s-i),y=new Set;for(const{overlayLines:u,row:v,col:m,w:h}of r)for(let c=0;c<u.length;c++){const d=w+v+c;if(d>=0&&d<n.length){const p=L(u[c])>h?P(u[c],0,h,!0):u[c];n[d]=this.compositeLineAt(n[d],p,m,h,t),y.add(d)}}for(const u of y)L(n[u])>t&&(n[u]=P(n[u],0,t,!0));return n}static SEGMENT_RESET="\x1B[0m\x1B]8;;\x07";applyLineResets(e){const t=D.SEGMENT_RESET;for(let i=0;i<e.length;i++){const n=e[i];I(n)||(e[i]=n+t)}return e}compositeLineAt(e,t,i,n,r){if(I(e))return e;const l=i+n,s=J(e,i,l,r-l,!0),w=Y(t,0,n,!0),y=Math.max(0,i-s.beforeWidth),u=Math.max(0,n-w.width),v=Math.max(i,s.beforeWidth),m=Math.max(n,w.width),h=Math.max(0,r-v-m),c=Math.max(0,h-s.afterWidth),d=D.SEGMENT_RESET,p=s.before+" ".repeat(y)+d+w.text+" ".repeat(u)+d+s.after+" ".repeat(c);return L(p)<=r?p:P(p,0,r,!0)}extractCursorPosition(e,t){const i=Math.max(0,e.length-t);for(let n=e.length-1;n>=i;n--){const r=e[n],l=r.indexOf(F);if(l!==-1){const s=r.slice(0,l),w=L(s);return e[n]=r.slice(0,l)+r.slice(l+F.length),{row:n,col:w}}}return null}doRender(){if(this.stopped)return;const e=this.terminal.columns,t=this.terminal.rows;this.debugLog(`doRender: width=${e} height=${t} stopped=${this.stopped} children=${this.children.length}`);let i=Math.max(0,this.maxLinesRendered-t),n=this.previousViewportTop,r=this.hardwareCursorRow;const l=b(o=>{const a=r-n;return o-i-a},"computeLineDiff");let s=this.render(e);this.overlayStack.length>0&&(s=this.compositeOverlays(s,e,t));const w=this.extractCursorPosition(s,t);s=this.applyLineResets(s);const y=this.previousWidth!==0&&this.previousWidth!==e,u=b(o=>{this.fullRedrawCount+=1;let a="";o&&(a+="\x1B[3J\x1B[2J\x1B[H");for(let f=0;f<s.length;f++)f>0&&(a+=`\r
+`),a+=s[f];this.terminal.write(this.wrapRenderBuffer(a)),this.cursorRow=Math.max(0,s.length-1),this.hardwareCursorRow=this.cursorRow,o?this.maxLinesRendered=s.length:this.maxLinesRendered=Math.max(this.maxLinesRendered,s.length),this.previousViewportTop=Math.max(0,this.maxLinesRendered-t),this.positionHardwareCursor(w,s.length),this.previousLines=s,this.previousWidth=e},"fullRender"),v=process.env.CATUI_DEBUG_REDRAW==="1",m=b(o=>{if(!v)return;const a=k.join(V.homedir(),".catui","agent","catui-debug.log"),f=`[${new Date().toISOString()}] fullRender: ${o} (prev=${this.previousLines.length}, new=${s.length}, height=${t})
+`;$.appendFileSync(a,f)},"logRedraw");if(this.previousLines.length===0&&!y){m("first render"),u(!1);return}if(y){m(`width changed (${this.previousWidth} -> ${e})`),u(!0);return}if(this.clearOnShrink&&s.length<this.maxLinesRendered&&this.overlayStack.length===0){m(`clearOnShrink (maxLinesRendered=${this.maxLinesRendered})`),u(!0);return}let h=-1,c=-1;const d=Math.max(s.length,this.previousLines.length);for(let o=0;o<d;o++){const a=o<this.previousLines.length?this.previousLines[o]:"",f=o<s.length?s[o]:"";a!==f&&(h===-1&&(h=o),c=o)}const p=s.length>this.previousLines.length;p&&(h===-1&&(h=this.previousLines.length),c=s.length-1);const x=p&&h===this.previousLines.length&&h>0;if(h===-1){this.positionHardwareCursor(w,s.length),this.previousViewportTop=Math.max(0,this.maxLinesRendered-t);return}if(h>=s.length){if(this.previousLines.length>s.length){let o="";const a=Math.max(0,s.length-1),f=l(a);f>0?o+=`\x1B[${f}B`:f<0&&(o+=`\x1B[${-f}A`),o+="\r";const S=this.previousLines.length-s.length;if(S>t){m(`extraLines > height (${S} > ${t})`),u(!0);return}S>0&&(o+="\x1B[1B");for(let B=0;B<S;B++)o+="\r\x1B[2K",B<S-1&&(o+="\x1B[1B");S>0&&(o+=`\x1B[${S}A`),this.terminal.write(this.wrapRenderBuffer(o)),this.cursorRow=a,this.hardwareCursorRow=a}this.positionHardwareCursor(w,s.length),this.previousLines=s,this.previousWidth=e,this.previousViewportTop=Math.max(0,this.maxLinesRendered-t);return}const C=Math.max(0,this.previousLines.length-t);if(h<C){m(`firstChanged < viewportTop (${h} < ${C})`),u(!0);return}let g="";const M=n+t-1,A=x?h-1:h;if(A>M){const o=Math.max(0,Math.min(t-1,r-n)),a=t-1-o;a>0&&(g+=`\x1B[${a}B`);const f=A-M;g+=`\r
+`.repeat(f),n+=f,i+=f,r=A}const O=l(A);O>0?g+=`\x1B[${O}B`:O<0&&(g+=`\x1B[${-O}A`),g+=x?`\r
+`:"\r";const T=Math.min(c,s.length-1);for(let o=h;o<=T;o++){o>h&&(g+=`\r
+`),g+="\x1B[2K";const a=s[o];if(!I(a)&&L(a)>e){const S=k.join(V.homedir(),".catui","agent","catui-crash.log"),B=[`Crash at ${new Date().toISOString()}`,`Terminal width: ${e}`,`Line ${o} visible width: ${L(a)}`,"","=== All rendered lines ===",...s.map((U,H)=>`[${H}] (w=${L(U)}) ${U}`),""].join(`
+`);$.mkdirSync(k.dirname(S),{recursive:!0}),$.writeFileSync(S,B),this.stop();const z=[`Rendered line ${o} exceeds terminal width (${L(a)} > ${e}).`,"","This is likely caused by a custom TUI component not truncating its output.","Use visibleWidth() to measure and truncateToWidth() to truncate lines.","",`Debug log written to: ${S}`].join(`
+`);throw new Error(z)}g+=a}let E=T;if(this.previousLines.length>s.length){if(T<s.length-1){const a=s.length-1-T;g+=`\x1B[${a}B`,E=s.length-1}const o=this.previousLines.length-s.length;for(let a=s.length;a<this.previousLines.length;a++)g+=`\r
+\x1B[2K`;g+=`\x1B[${o}A`}if(process.env.CATUI_TUI_DEBUG==="1"){const o="/tmp/tui";$.mkdirSync(o,{recursive:!0});const a=k.join(o,`render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`),f=[`firstChanged: ${h}`,`viewportTop: ${i}`,`cursorRow: ${this.cursorRow}`,`height: ${t}`,`lineDiff: ${O}`,`hardwareCursorRow: ${r}`,`renderEnd: ${T}`,`finalCursorRow: ${E}`,`cursorPos: ${JSON.stringify(w)}`,`newLines.length: ${s.length}`,`previousLines.length: ${this.previousLines.length}`,"","=== newLines ===",JSON.stringify(s,null,2),"","=== previousLines ===",JSON.stringify(this.previousLines,null,2),"","=== buffer ===",JSON.stringify(g)].join(`
+`);$.writeFileSync(a,f)}this.terminal.write(this.wrapRenderBuffer(g)),this.cursorRow=Math.max(0,s.length-1),this.hardwareCursorRow=E,this.maxLinesRendered=Math.max(this.maxLinesRendered,s.length),this.previousViewportTop=Math.max(0,this.maxLinesRendered-t),this.positionHardwareCursor(w,s.length),this.previousLines=s,this.previousWidth=e}positionHardwareCursor(e,t){if(!e||t<=0){this.terminal.hideCursor();return}const i=Math.max(0,Math.min(e.row,t-1)),n=Math.max(0,e.col),r=i-this.hardwareCursorRow;let l="";r>0?l+=`\x1B[${r}B`:r<0&&(l+=`\x1B[${-r}A`),l+=`\x1B[${n+1}G`,l&&this.terminal.write(l),this.hardwareCursorRow=i,this.showHardwareCursor?this.terminal.showCursor():this.terminal.hideCursor()}}export{F as CURSOR_MARKER,X as Container,D as TUI,_ as isFocusable,L as visibleWidth};

package/dist/core/lib/tui/src/undo-stack.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic undo stack with clone-on-push semantics.
+ *
+ * Stores deep clones of state snapshots. Popped snapshots are returned
+ * directly (no re-cloning) since they are already detached.
+ */
+/**
+ * [WHO]: UndoStack
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/lib/tui/src/index.ts
+ * [HERE]: core/lib/tui/src/undo-stack.ts -
+ */
+export declare class UndoStack<S> {
+    private stack;
+    /** Push a deep clone of the given state onto the stack. */
+    push(state: S): void;
+    /** Pop and return the most recent snapshot, or undefined if empty. */
+    pop(): S | undefined;
+    /** Remove all snapshots. */
+    clear(): void;
+    get length(): number;
+}

package/dist/core/lib/tui/src/undo-stack.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var e=(s,t)=>c(s,"name",{value:t,configurable:!0});class a{static{e(this,"UndoStack")}stack=[];push(t){this.stack.push(structuredClone(t))}pop(){return this.stack.pop()}clear(){this.stack.length=0}get length(){return this.stack.length}}export{a as UndoStack};

package/dist/core/lib/tui/src/utils.d.ts

@@ -0,0 +1,83 @@
+/**
+ * [WHO]: getSegmenter, visibleWidth, wrapTextWithAnsi, isWhitespaceChar, isPunctuationChar
+ * [FROM]: Depends on get-east-asian-width
+ * [TO]: Consumed by core/lib/tui/src/index.ts
+ * [HERE]: core/lib/tui/src/utils.ts -
+ */
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export declare function getSegmenter(): Intl.Segmenter;
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export declare function visibleWidth(str: string): number;
+/**
+ * Extract ANSI escape sequences from a string at the given position.
+ */
+export declare function extractAnsiCode(str: string, pos: number): {
+    code: string;
+    length: number;
+} | null;
+/**
+ * Wrap text with ANSI codes preserved.
+ *
+ * ONLY does word wrapping - NO padding, NO background colors.
+ * Returns lines where each line is <= width visible chars.
+ * Active ANSI codes are preserved across line breaks.
+ *
+ * @param text - Text to wrap (may contain ANSI codes and newlines)
+ * @param width - Maximum visible width per line
+ * @returns Array of wrapped lines (NOT padded to width)
+ */
+export declare function wrapTextWithAnsi(text: string, width: number): string[];
+/**
+ * Check if a character is whitespace.
+ */
+export declare function isWhitespaceChar(char: string): boolean;
+/**
+ * Check if a character is punctuation.
+ */
+export declare function isPunctuationChar(char: string): boolean;
+/**
+ * Apply background color to a line, padding to full width.
+ *
+ * @param line - Line of text (may contain ANSI codes)
+ * @param width - Total width to pad to
+ * @param bgFn - Background color function
+ * @returns Line with background applied and padded to width
+ */
+export declare function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string;
+/**
+ * Truncate text to fit within a maximum visible width, adding ellipsis if needed.
+ * Optionally pad with spaces to reach exactly maxWidth.
+ * Properly handles ANSI escape codes (they don't count toward width).
+ *
+ * @param text - Text to truncate (may contain ANSI codes)
+ * @param maxWidth - Maximum visible width
+ * @param ellipsis - Ellipsis string to append when truncating (default: "...")
+ * @param pad - If true, pad result with spaces to exactly maxWidth (default: false)
+ * @returns Truncated text, optionally padded to exactly maxWidth
+ */
+export declare function truncateToWidth(text: string, maxWidth: number, ellipsis?: string, pad?: boolean): string;
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ * @param strict - If true, exclude wide chars at boundary that would extend past the range
+ */
+export declare function sliceByColumn(line: string, startCol: number, length: number, strict?: boolean): string;
+/** Like sliceByColumn but also returns the actual visible width of the result. */
+export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean): {
+    text: string;
+    width: number;
+};
+/**
+ * Extract "before" and "after" segments from a line in a single pass.
+ * Used for overlay compositing where we need content before and after the overlay region.
+ * Preserves styling from before the overlay that should affect content after it.
+ */
+export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter?: boolean): {
+    before: string;
+    beforeWidth: number;
+    after: string;
+    afterWidth: number;
+};

package/dist/core/lib/tui/src/utils.js

@@ -0,0 +1,2 @@
+var $=Object.defineProperty;var g=(e,n)=>$(e,"name",{value:n,configurable:!0});import{eastAsianWidth as R}from"get-east-asian-width";const m=new Intl.Segmenter(void 0,{granularity:"grapheme"});function D(){return m}g(D,"getSegmenter");function y(e){const n=e.codePointAt(0);return n>=126976&&n<=130047||n>=8960&&n<=9215||n>=9728&&n<=10175||n>=11088&&n<=11093||e.includes("\uFE0F")||e.length>2}g(y,"couldBeEmoji");const P=new RegExp("^(?:\\p{Default_Ignorable_Code_Point}|\\p{Control}|\\p{Mark}|\\p{Surrogate})+$","v"),T=new RegExp("^[\\p{Default_Ignorable_Code_Point}\\p{Control}\\p{Format}\\p{Mark}\\p{Surrogate}]+","v"),_=new RegExp("^\\p{RGI_Emoji}$","v"),I=512,C=new Map;function w(e){if(P.test(e))return 0;if(y(e)&&_.test(e))return 2;const o=e.replace(T,"").codePointAt(0);if(o===void 0)return 0;if(o>=127462&&o<=127487)return 2;let t=R(o);if(e.length>1)for(const r of e.slice(1)){const i=r.codePointAt(0);i>=65280&&i<=65519&&(t+=R(i))}return t}g(w,"graphemeWidth");function x(e){if(e.length===0)return 0;let n=!0;for(let i=0;i<e.length;i++){const s=e.charCodeAt(i);if(s<32||s>126){n=!1;break}}if(n)return e.length;const o=C.get(e);if(o!==void 0)return o;let t=e;e.includes("	")&&(t=t.replace(/\t/g,"   ")),t.includes("\x1B")&&(t=t.replace(/\x1b\[[0-9;]*[mGKHJ]/g,""),t=t.replace(/\x1b\]8;;[^\x07]*\x07/g,""),t=t.replace(/\x1b_[^\x07\x1b]*(?:\x07|\x1b\\)/g,""));let r=0;for(const{segment:i}of m.segment(t))r+=w(i);if(C.size>=I){const i=C.keys().next().value;i!==void 0&&C.delete(i)}return C.set(e,r),r}g(x,"visibleWidth");function k(e,n){if(n>=e.length||e[n]!=="\x1B")return null;const o=e[n+1];if(o==="["){let t=n+2;for(;t<e.length&&!/[mGKHJ]/.test(e[t]);)t++;return t<e.length?{code:e.substring(n,t+1),length:t+1-n}:null}if(o==="]"){let t=n+2;for(;t<e.length;){if(e[t]==="\x07")return{code:e.substring(n,t+1),length:t+1-n};if(e[t]==="\x1B"&&e[t+1]==="\\")return{code:e.substring(n,t+2),length:t+2-n};t++}return null}if(o==="_"){let t=n+2;for(;t<e.length;){if(e[t]==="\x07")return{code:e.substring(n,t+1),length:t+1-n};if(e[t]==="\x1B"&&e[t+1]==="\\")return{code:e.substring(n,t+2),length:t+2-n};t++}return null}return null}g(k,"extractAnsiCode");class W{static{g(this,"AnsiCodeTracker")}bold=!1;dim=!1;italic=!1;underline=!1;blink=!1;inverse=!1;hidden=!1;strikethrough=!1;fgColor=null;bgColor=null;process(n){if(!n.endsWith("m"))return;const o=n.match(/\x1b\[([\d;]*)m/);if(!o)return;const t=o[1];if(t===""||t==="0"){this.reset();return}const r=t.split(";");let i=0;for(;i<r.length;){const s=Number.parseInt(r[i],10);if(s===38||s===48){if(r[i+1]==="5"&&r[i+2]!==void 0){const l=`${r[i]};${r[i+1]};${r[i+2]}`;s===38?this.fgColor=l:this.bgColor=l,i+=3;continue}else if(r[i+1]==="2"&&r[i+4]!==void 0){const l=`${r[i]};${r[i+1]};${r[i+2]};${r[i+3]};${r[i+4]}`;s===38?this.fgColor=l:this.bgColor=l,i+=5;continue}}switch(s){case 0:this.reset();break;case 1:this.bold=!0;break;case 2:this.dim=!0;break;case 3:this.italic=!0;break;case 4:this.underline=!0;break;case 5:this.blink=!0;break;case 7:this.inverse=!0;break;case 8:this.hidden=!0;break;case 9:this.strikethrough=!0;break;case 21:this.bold=!1;break;case 22:this.bold=!1,this.dim=!1;break;case 23:this.italic=!1;break;case 24:this.underline=!1;break;case 25:this.blink=!1;break;case 27:this.inverse=!1;break;case 28:this.hidden=!1;break;case 29:this.strikethrough=!1;break;case 39:this.fgColor=null;break;case 49:this.bgColor=null;break;default:s>=30&&s<=37||s>=90&&s<=97?this.fgColor=String(s):(s>=40&&s<=47||s>=100&&s<=107)&&(this.bgColor=String(s));break}i++}}reset(){this.bold=!1,this.dim=!1,this.italic=!1,this.underline=!1,this.blink=!1,this.inverse=!1,this.hidden=!1,this.strikethrough=!1,this.fgColor=null,this.bgColor=null}clear(){this.reset()}getActiveCodes(){const n=[];return this.bold&&n.push("1"),this.dim&&n.push("2"),this.italic&&n.push("3"),this.underline&&n.push("4"),this.blink&&n.push("5"),this.inverse&&n.push("7"),this.hidden&&n.push("8"),this.strikethrough&&n.push("9"),this.fgColor&&n.push(this.fgColor),this.bgColor&&n.push(this.bgColor),n.length===0?"":`\x1B[${n.join(";")}m`}hasActiveCodes(){return this.bold||this.dim||this.italic||this.underline||this.blink||this.inverse||this.hidden||this.strikethrough||this.fgColor!==null||this.bgColor!==null}getLineEndReset(){return this.underline?"\x1B[24m":""}}function L(e,n){let o=0;for(;o<e.length;){const t=k(e,o);t?(n.process(t.code),o+=t.length):o++}}g(L,"updateTrackerFromText");function S(e){const n=[];let o="",t="",r=!1,i=0;for(;i<e.length;){const s=k(e,i);if(s){t+=s.code,i+=s.length;continue}const l=e[i],f=l===" ";f!==r&&o&&(n.push(o),o=""),t&&(o+=t,t=""),r=f,o+=l,i++}return t&&(o+=t),o&&n.push(o),n}g(S,"splitIntoTokensWithAnsi");function K(e,n){if(!e)return[""];const o=e.split(`
+`),t=[],r=new W;for(const i of o){const s=t.length>0?r.getActiveCodes():"";t.push(...j(s+i,n)),L(i,r)}return t.length>0?t:[""]}g(K,"wrapTextWithAnsi");function j(e,n){if(!e)return[""];if(x(e)<=n)return[e];const t=[],r=new W,i=S(e);let s="",l=0;for(const f of i){const c=x(f),a=f.trim()==="";if(c>n&&!a){if(s){const h=r.getLineEndReset();h&&(s+=h),t.push(s),s="",l=0}const u=M(f,n,r);t.push(...u.slice(0,-1)),s=u[u.length-1],l=x(s);continue}if(l+c>n&&l>0){let u=s.trimEnd();const h=r.getLineEndReset();h&&(u+=h),t.push(u),a?(s=r.getActiveCodes(),l=0):(s=r.getActiveCodes()+f,l=c)}else s+=f,l+=c;L(f,r)}return s&&t.push(s),t.length>0?t.map(f=>f.trimEnd()):[""]}g(j,"wrapSingleLine");const N=/[(){}[\]<>.,;:'"!?+\-=*/\\|&%^$#@~`]/;function V(e){return/\s/.test(e)}g(V,"isWhitespaceChar");function z(e){return N.test(e)}g(z,"isPunctuationChar");function M(e,n,o){const t=[];let r=o.getActiveCodes(),i=0,s=0;const l=[];for(;s<e.length;){const f=k(e,s);if(f)l.push({type:"ansi",value:f.code}),s+=f.length;else{let c=s;for(;c<e.length&&!k(e,c);)c++;const a=e.slice(s,c);for(const d of m.segment(a))l.push({type:"grapheme",value:d.segment});s=c}}for(const f of l){if(f.type==="ansi"){r+=f.value,o.process(f.value);continue}const c=f.value;if(!c)continue;const a=x(c);if(i+a>n){const d=o.getLineEndReset();d&&(r+=d),t.push(r),r=o.getActiveCodes(),i=0}r+=c,i+=a}return r&&t.push(r),t.length>0?t:[""]}g(M,"breakLongWord");function J(e,n,o){const t=x(e),r=Math.max(0,n-t),i=" ".repeat(r),s=e+i;return o(s)}g(J,"applyBackgroundToLine");function U(e,n,o="...",t=!1){const r=x(e);if(r<=n)return t?e+" ".repeat(n-r):e;const i=x(o),s=n-i;if(s<=0)return o.substring(0,n);let l=0;const f=[];for(;l<e.length;){const u=k(e,l);if(u)f.push({type:"ansi",value:u.code}),l+=u.length;else{let h=l;for(;h<e.length&&!k(e,h);)h++;const b=e.slice(l,h);for(const p of m.segment(b))f.push({type:"grapheme",value:p.segment});l=h}}let c="",a=0;for(const u of f){if(u.type==="ansi"){c+=u.value;continue}const h=u.value;if(!h)continue;const b=x(h);if(a+b>s)break;c+=h,a+=b}const d=`${c}\x1B[0m${o}`;if(t){const u=x(d);return d+" ".repeat(Math.max(0,n-u))}return d}g(U,"truncateToWidth");function O(e,n,o,t=!1){return B(e,n,o,t).text}g(O,"sliceByColumn");function B(e,n,o,t=!1){if(o<=0)return{text:"",width:0};const r=n+o;let i="",s=0,l=0,f=0,c="";for(;f<e.length;){const a=k(e,f);if(a){l>=n&&l<r?i+=a.code:l<n&&(c+=a.code),f+=a.length;continue}let d=f;for(;d<e.length&&!k(e,d);)d++;for(const{segment:u}of m.segment(e.slice(f,d))){const h=w(u),b=l>=n&&l<r,p=!t||l+h<=r;if(b&&p&&(c&&(i+=c,c=""),i+=u,s+=h),l+=h,l>=r)break}if(f=d,l>=r)break}return{text:i,width:s}}g(B,"sliceWithWidth");const E=new W;function X(e,n,o,t,r=!1){let i="",s=0,l="",f=0,c=0,a=0,d="",u=!1;const h=o+t;for(E.clear();a<e.length;){const b=k(e,a);if(b){E.process(b.code),c<n?d+=b.code:c>=o&&c<h&&u&&(l+=b.code),a+=b.length;continue}let p=a;for(;p<e.length&&!k(e,p);)p++;for(const{segment:A}of m.segment(e.slice(a,p))){const v=w(A);if(c<n?(d&&(i+=d,d=""),i+=A,s+=v):c>=o&&c<h&&(!r||c+v<=h)&&(u||(l+=E.getActiveCodes(),u=!0),l+=A,f+=v),c+=v,t<=0?c>=n:c>=h)break}if(a=p,t<=0?c>=n:c>=h)break}return{before:i,beforeWidth:s,after:l,afterWidth:f}}g(X,"extractSegments");export{J as applyBackgroundToLine,k as extractAnsiCode,X as extractSegments,D as getSegmenter,z as isPunctuationChar,V as isWhitespaceChar,O as sliceByColumn,B as sliceWithWidth,U as truncateToWidth,x as visibleWidth,K as wrapTextWithAnsi};

package/dist/core/mcp/figma-auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * [WHO]: registerFigmaMcpOAuthProvider()
+ * [FROM]: Depends on ai, node:fs, node:http, node:os, node:path, node:child_process
+ * [TO]: Consumed by core/runtime/sdk.ts
+ * [HERE]: core/mcp/figma-auth.ts - Figma OAuth integration for MCP servers
+ */
+import { type OAuthCredentials } from "@catui/ai/oauth";
+export type FigmaOAuthCredentials = OAuthCredentials & {
+    clientId: string;
+    clientSecret?: string;
+    tokenEndpointAuthMethod?: "client_secret_basic" | "client_secret_post" | "none";
+    scope?: string;
+    source?: string;
+};
+export type FigmaImportableSession = {
+    source: string;
+    expiresAt: number;
+};
+export declare function findImportableFigmaOAuthSession(): FigmaImportableSession | undefined;
+export declare function refreshFigmaOAuthCredentials(credentials: FigmaOAuthCredentials): Promise<FigmaOAuthCredentials>;
+export declare function registerFigmaMcpOAuthProvider(): void;

package/dist/core/mcp/figma-auth.js

@@ -0,0 +1,22 @@
+var P=Object.defineProperty;var i=(e,n)=>P(e,"name",{value:n,configurable:!0});import{registerOAuthProvider as k}from"@catui/ai/oauth";import{existsSync as M,readFileSync as U}from"node:fs";import{createServer as L}from"node:http";import{homedir as v}from"node:os";import{join as x}from"node:path";import{exec as R}from"node:child_process";const g="https://mcp.figma.com/mcp",le="https://mcp.figma.com/.well-known/oauth-protected-resource",O="https://api.figma.com/.well-known/oauth-authorization-server",$="https://www.figma.com/oauth/mcp",C="https://api.figma.com/v1/oauth/token",he="https://api.figma.com/v1/oauth/mcp/register",m="mcp:connect",z="Catui",G="https://github.com/catui-agent/catui-agent",j="https://raw.githubusercontent.com/catui-agent/catui-agent/main/README.md",E=x(v(),".claude",".credentials.json"),A="127.0.0.1",S="/auth/callback",N=[14565,14566,14567,14568,14569],D=`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Figma authentication successful</title>
+</head>
+<body>
+  <p>Figma authentication completed. Return to Catui.</p>
+</body>
+</html>`,B=`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Figma authentication failed</title>
+</head>
+<body>
+  <p>Figma authentication failed. You can close this window and retry from Catui.</p>
+</body>
+</html>`;function I(e){let n="";for(const t of e)n+=String.fromCharCode(t);return btoa(n).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}i(I,"base64urlEncode");async function H(){const e=new Uint8Array(32);crypto.getRandomValues(e);const n=I(e),t=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(n)),r=I(new Uint8Array(t));return{verifier:n,challenge:r}}i(H,"generatePKCE");function K(e){const n=process.platform==="darwin"?`open "${e}"`:process.platform==="win32"?`start "" "${e}"`:`xdg-open "${e}"`;R(n,()=>{})}i(K,"openBrowser");function W(){const e=new Uint8Array(16);return crypto.getRandomValues(e),Buffer.from(e).toString("hex")}i(W,"createState");function J(e,n){if(!(!e.accessToken||!e.refreshToken||!e.clientId))return{access:e.accessToken,refresh:e.refreshToken,expires:typeof e.expiresAt=="number"?e.expiresAt:0,clientId:e.clientId,clientSecret:e.clientSecret,tokenEndpointAuthMethod:e.clientSecret?"client_secret_basic":"none",scope:e.stepUpScope||m,source:n}}i(J,"normalizeImportedCredentials");function F(){if(M(E))try{const e=JSON.parse(U(E,"utf-8"));return Object.values(e.mcpOAuth??{}).filter(t=>t.serverUrl===g).map(t=>J(t,"Claude Code")).filter(t=>!!t).sort((t,r)=>r.expires-t.expires)[0]}catch{return}}i(F,"loadClaudeFigmaCredentials");function fe(){const e=F();if(e)return{source:e.source||"Claude Code",expiresAt:e.expires}}i(fe,"findImportableFigmaOAuthSession");function V(){const e=process.env.CATUI_FIGMA_CLIENT_ID?.trim();if(!e)return;const n=process.env.CATUI_FIGMA_CLIENT_SECRET?.trim()||void 0;return{clientId:e,clientSecret:n,tokenEndpointAuthMethod:n?"client_secret_basic":"none",source:"environment"}}i(V,"loadConfiguredClientInformation");async function q(e,n){const t={"Content-Type":"application/x-www-form-urlencoded",Accept:"application/json"},r=new URLSearchParams({grant_type:"refresh_token",refresh_token:e.refresh,resource:g});if(n==="client_secret_basic"){if(!e.clientSecret)return;const o=Buffer.from(`${e.clientId}:${e.clientSecret}`,"utf8").toString("base64");t.Authorization=`Basic ${o}`}else r.set("client_id",e.clientId),n==="client_secret_post"&&e.clientSecret&&r.set("client_secret",e.clientSecret);const a=await fetch(C,{method:"POST",headers:t,body:r});if(!a.ok)return;const c=await a.json();if(!(!c.access_token||typeof c.expires_in!="number"))return{...e,access:c.access_token,refresh:c.refresh_token||e.refresh,expires:Date.now()+c.expires_in*1e3}}i(q,"requestRefresh");async function y(e){const n=e.tokenEndpointAuthMethod??(e.clientSecret?"client_secret_basic":"none"),t=n==="client_secret_basic"?["client_secret_basic","client_secret_post","none"]:n==="client_secret_post"?["client_secret_post","client_secret_basic","none"]:["none","client_secret_basic","client_secret_post"];for(const r of t){const a=await q(e,r);if(a)return{...a,tokenEndpointAuthMethod:r}}throw new Error("Failed to refresh Figma MCP OAuth credentials")}i(y,"refreshFigmaOAuthCredentials");async function Y(){const e=await fetch(O,{headers:{Accept:"application/json"}});if(!e.ok)throw new Error(`Failed to fetch Figma authorization metadata (${e.status} ${e.statusText})`);return await e.json()}i(Y,"fetchAuthorizationServerMetadata");async function Q(e,n){if(!n.registration_endpoint)return;const t=await fetch(n.registration_endpoint,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify({client_name:z,redirect_uris:[e],grant_types:["authorization_code","refresh_token"],response_types:["code"],token_endpoint_auth_method:"client_secret_basic",client_uri:G,client_metadata_url:j,scope:m})});if(!t.ok)return;const r=await t.json();if(r.client_id)return{clientId:r.client_id,clientSecret:r.client_secret,tokenEndpointAuthMethod:r.token_endpoint_auth_method||(r.client_secret?"client_secret_basic":"none"),source:"dynamic-registration"}}i(Q,"registerCatuiClient");function T(e){const n=e.trim();if(!n)return{};try{const t=new URL(n);return{code:t.searchParams.get("code")??void 0,state:t.searchParams.get("state")??void 0}}catch{}if(n.includes("code=")){const t=new URLSearchParams(n);return{code:t.get("code")??void 0,state:t.get("state")??void 0}}return{code:n}}i(T,"parseAuthorizationInput");async function X(e){let n=null,t=!1;for(const r of N)try{const a=await new Promise((c,o)=>{const s=L((f,u)=>{try{const l=new URL(f.url||"",`http://${A}:${r}`);if(l.pathname!==S){u.statusCode=404,u.end("Not found");return}const h=l.searchParams.get("code"),p=l.searchParams.get("state"),_=l.searchParams.get("error");if(h&&p){n={code:h,state:p},u.statusCode=200,u.setHeader("Content-Type","text/html; charset=utf-8"),u.end(D);return}u.statusCode=400,u.setHeader("Content-Type","text/html; charset=utf-8"),u.end(B+(_?`
+<!-- ${_} -->`:""))}catch{u.statusCode=500,u.end("Internal error")}});s.once("error",o),s.listen(r,A,()=>{s.removeListener("error",o),c(s)})});return e?.addEventListener("abort",()=>{t=!0,a.close()},{once:!0}),{server:a,redirectUri:`http://${A}:${r}${S}`,cancelWait:i(()=>{t=!0},"cancelWait"),waitForCode:i(async()=>{const c=i(()=>new Promise(o=>setTimeout(o,100)),"sleep");for(let o=0;o<1800;o+=1){if(n)return n;if(t)return null;await c()}return null},"waitForCode")}}catch{}throw new Error("Failed to start a local OAuth callback server for Figma")}i(X,"startCallbackServer");function Z(e,n,t,r,a,c){const o=new URL(c.authorization_endpoint||$);return o.searchParams.set("response_type","code"),o.searchParams.set("client_id",e.clientId),o.searchParams.set("redirect_uri",n),o.searchParams.set("scope",a),o.searchParams.set("code_challenge",r),o.searchParams.set("code_challenge_method","S256"),o.searchParams.set("state",t),o.searchParams.set("resource",g),o.toString()}i(Z,"buildAuthorizationUrl");async function ee(e,n,t,r){const a=r.tokenEndpointAuthMethod??(r.clientSecret?"client_secret_basic":"none"),c={"Content-Type":"application/x-www-form-urlencoded",Accept:"application/json"},o=new URLSearchParams({grant_type:"authorization_code",code:e,code_verifier:n,redirect_uri:t,resource:g});if(a==="client_secret_basic"){if(!r.clientSecret)throw new Error("Figma OAuth client is missing client_secret for client_secret_basic");c.Authorization=`Basic ${Buffer.from(`${r.clientId}:${r.clientSecret}`,"utf8").toString("base64")}`}else o.set("client_id",r.clientId),a==="client_secret_post"&&r.clientSecret&&o.set("client_secret",r.clientSecret);const s=await fetch(C,{method:"POST",headers:c,body:o});if(!s.ok){const u=await s.text().catch(()=>"");throw new Error(`Figma authorization code exchange failed (${s.status} ${s.statusText})${u?`: ${u}`:""}`)}const f=await s.json();if(!f.access_token||!f.refresh_token||typeof f.expires_in!="number")throw new Error("Figma OAuth token response did not include the expected fields");return{access:f.access_token,refresh:f.refresh_token,expires:Date.now()+f.expires_in*1e3,clientId:r.clientId,clientSecret:r.clientSecret,tokenEndpointAuthMethod:a,scope:m,source:r.source||"catui"}}i(ee,"exchangeAuthorizationCode");async function te(e){e.onProgress?.("Preparing a standalone Figma OAuth flow...");const n=await Y(),t=await X(e.signal);try{const a=V()||await Q(t.redirectUri,n);if(!a)throw new Error("Catui could not complete Figma dynamic client registration. Set CATUI_FIGMA_CLIENT_ID and CATUI_FIGMA_CLIENT_SECRET, or keep using the import fallback for now.");const{verifier:c,challenge:o}=await H(),s=W(),f=(n.scopes_supported?.includes(m),m),u=Z(a,t.redirectUri,s,o,f,n);e.onAuth({url:u,instructions:"A browser window should open. Approve Figma access to finish linking Catui."}),K(u);let l;if(e.onManualCodeInput){let h,p;const _=e.onManualCodeInput().then(d=>{h=d,t.cancelWait()}).catch(d=>{p=d instanceof Error?d:new Error(String(d)),t.cancelWait()}),w=await t.waitForCode();if(p)throw p;if(w?.code){if(w.state!==s)throw new Error("Figma OAuth state mismatch");l=w.code}else if(h){const d=T(h);if(d.state&&d.state!==s)throw new Error("Figma OAuth state mismatch");l=d.code}if(!l){if(await _,p)throw p;if(h){const d=T(h);if(d.state&&d.state!==s)throw new Error("Figma OAuth state mismatch");l=d.code}}}else{const h=await t.waitForCode();if(h?.state&&h.state!==s)throw new Error("Figma OAuth state mismatch");l=h?.code}if(!l)throw new Error("Figma OAuth did not complete");return e.onProgress?.("Finishing Figma authorization..."),await ee(l,c,t.redirectUri,a)}finally{t.server.close()}}i(te,"loginWithStandaloneOAuth");async function ne(e){try{return await te(e)}catch(n){e.onProgress?.("Standalone Figma OAuth was unavailable. Checking for an importable official session...");const t=F();if(!t)throw n;return e.onProgress?.(`Refreshing the imported Figma session from ${t.source}...`),await y(t)}}i(ne,"loginFigma");const re={id:"figma",name:"Figma MCP",usesCallbackServer:!0,async login(e){return await ne(e)},async refreshToken(e){return await y(e)},getApiKey(e){return String(e.access??"")}};let b=!1;function pe(){b||(k(re),b=!0)}i(pe,"registerFigmaMcpOAuthProvider");export{fe as findImportableFigmaOAuthSession,y as refreshFigmaOAuthCredentials,pe as registerFigmaMcpOAuthProvider};

package/dist/core/mcp/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [WHO]: MCP module barrel exports
+ * [FROM]: Depends on mcp-client, mcp-adapter, mcp-config, mcp-guidance, figma-auth
+ * [TO]: Consumed by core/index.ts
+ * [HERE]: core/mcp/index.ts - MCP module public API
+ */
+export { MCPClient } from "./mcp-client.js";
+export type { MCPServerConfig, MCPTool, MCPToolResult } from "./mcp-types.js";
+export { createMCPTool, getMCPToolDisplayName, loadMCPTools, } from "./mcp-adapter.js";
+export { API_KEY_GUIDANCE, formatGuidanceMessage, getAPIKeyGuidance, getMissingKeyServers, getOptionalAPIKeyServers, requiresAPIKey, } from "./mcp-guidance.js";
+export type { APIKeyGuidance } from "./mcp-guidance.js";

package/dist/core/mcp/index.js

@@ -0,0 +1 @@
+import{MCPClient as r}from"./mcp-client.js";import{createMCPTool as a,getMCPToolDisplayName as s,loadMCPTools as i}from"./mcp-adapter.js";import{API_KEY_GUIDANCE as l,formatGuidanceMessage as g,getAPIKeyGuidance as C,getMissingKeyServers as M,getOptionalAPIKeyServers as m,requiresAPIKey as n}from"./mcp-guidance.js";export{l as API_KEY_GUIDANCE,r as MCPClient,a as createMCPTool,g as formatGuidanceMessage,C as getAPIKeyGuidance,s as getMCPToolDisplayName,M as getMissingKeyServers,m as getOptionalAPIKeyServers,i as loadMCPTools,n as requiresAPIKey};

package/dist/core/mcp/mcp-adapter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * [WHO]: createMCPTool(), loadMCPTools(), getMCPToolDisplayName()
+ * [FROM]: Depends on extensions, mcp-client, mcp-guidance
+ * [TO]: Consumed by core/mcp/index.ts, core/mcp/mcp-manager.ts
+ * [HERE]: core/mcp/mcp-adapter.ts - adapts MCP tools to Catui tool system
+ */
+import type { ToolDefinition } from "../extensions-host/index.js";
+import type { MCPClient } from "./mcp-client.js";
+import type { MCPTool } from "./mcp-types.js";
+/**
+ * Create a Catui ToolDefinition from an MCP tool definition
+ */
+export declare function createMCPTool(mcpClient: MCPClient, mcpTool: MCPTool): ToolDefinition;
+/**
+ * Load all MCP tools as Catui ToolDefinitions
+ */
+export declare function loadMCPTools(mcpClient: MCPClient): Promise<ToolDefinition[]>;
+/**
+ * Get a human-readable display name for an MCP tool
+ */
+export declare function getMCPToolDisplayName(mcpTool: MCPTool): string;

package/dist/core/mcp/mcp-adapter.js

@@ -0,0 +1,3 @@
+var f=Object.defineProperty;var s=(t,n)=>f(t,"name",{value:n,configurable:!0});import{formatGuidanceMessage as l,getAPIKeyGuidance as u}from"./mcp-guidance.js";function m(t){const n=`mcp_${t.replace(/[^a-zA-Z0-9_-]/g,"_")}`;if(n.length<=60)return n;let e=0;for(let a=0;a<t.length;a++)e=e*31+t.charCodeAt(a)|0;const i=Math.abs(e).toString(36);return`${n.slice(0,50)}_${i}`}s(m,"toSafeToolName");function x(t,n){const e=n.name,i=m(e),[a]=e.split("/");return{name:i,label:e,description:`${n.description} (MCP: ${e})`,parameters:n.inputSchema??{type:"object",properties:{},additionalProperties:!0},async execute(y,p,g,$,h){try{const r=await t.callTool(e,p);if(r.error){const o=u(a);return o&&r.error?.toLowerCase().includes("key")?{content:[{type:"text",text:l(o,!0)}],details:{error:r.error}}:{content:[{type:"text",text:r.content.map(d=>d.text||"").join(`
+`)}],details:{error:r.error}}}return{content:[{type:"text",text:r.content.map(o=>o.type==="text"?o.text||"":o.type==="image"?`[Image: ${o.data?.uri||"unknown"}]`:o.type==="resource"?`[Resource: ${JSON.stringify(o.data)}]`:"").filter(Boolean).join(`
+`)}],details:void 0}}catch(r){const c=u(a);return c&&String(r).toLowerCase().includes("key")?{content:[{type:"text",text:l(c,!0)}],details:{error:r instanceof Error?r.message:String(r)}}:{content:[{type:"text",text:`Failed to call MCP tool ${e}`}],details:{error:r instanceof Error?r.message:String(r)}}}}}}s(x,"createMCPTool");async function M(t){return(await t.listTools()).map(e=>x(t,e))}s(M,"loadMCPTools");function S(t){if(t.displayName)return t.displayName;const[n,...e]=t.name.split("/"),i=e.join("/");return`${n}/${i}`}s(S,"getMCPToolDisplayName");export{x as createMCPTool,S as getMCPToolDisplayName,M as loadMCPTools};

package/dist/core/mcp/mcp-client.d.ts

@@ -0,0 +1,91 @@
+import type { MCPServerConfig, MCPTool, MCPToolResult } from "./mcp-types.js";
+/**
+ * MCP Client class
+ * Manages connections to MCP servers and tool calls
+ */
+export declare class MCPClient {
+    private servers;
+    private serverRuntimes;
+    private serverTools;
+    private httpSessions;
+    private authStorage;
+    private agentDir?;
+    private mcpConfigPath?;
+    /**
+     * @param authStoragePath Optional path to auth.json. If omitted, uses getAgentDir()/auth.json.
+     * @param agentDir Optional agent directory for config path resolution. If omitted, uses getAgentDir().
+     * @param mcpConfigPath Optional explicit MCP config file path. Overrides default resolution.
+     */
+    constructor(authStoragePath?: string, agentDir?: string, mcpConfigPath?: string);
+    /**
+     * Load MCP server configurations from config file
+     */
+    private loadServersFromConfig;
+    /**
+     * Get all configured servers
+     */
+    getServers(): MCPServerConfig[];
+    /**
+     * Get a specific server by ID
+     */
+    getServer(id: string): MCPServerConfig | undefined;
+    /**
+     * Add or update a server configuration
+     */
+    addServer(server: MCPServerConfig): void;
+    /**
+     * Remove a server
+     */
+    removeServer(id: string): void;
+    private getRuntime;
+    private convertNpxArgsToNpmExecArgs;
+    private getSpawnAttempts;
+    private spawnProcess;
+    private attachStdoutParser;
+    private processStdoutBuffer;
+    private handleJsonRpcMessage;
+    private writeFramedMessage;
+    private sendNotification;
+    private sendRequest;
+    private getHttpSession;
+    private buildHttpHeaders;
+    private ensureHttpInitialized;
+    private sendHttpRequest;
+    private parseEventStreamResponse;
+    private initializeServer;
+    private normalizeToolRecord;
+    private loadToolsForServer;
+    /**
+     * Start an MCP server (for stdio transport)
+     */
+    startServer(serverId: string): Promise<boolean>;
+    /**
+     * Stop an MCP server
+     */
+    stopServer(serverId: string): void;
+    /**
+     * Stop all running servers
+     */
+    stopAllServers(): void;
+    /**
+     * List available tools from all servers
+     */
+    listTools(serverId?: string): Promise<MCPTool[]>;
+    /**
+     * Call an MCP tool
+     */
+    callTool(toolName: string, args: Record<string, unknown>, timeoutMs?: number): Promise<MCPToolResult>;
+    private callHttpTool;
+    /**
+     * Call tool via stdio (JSON-RPC)
+     */
+    private callStdioTool;
+    /**
+     * Call tool via SSE (HTTP)
+     */
+    private callSSETool;
+    /**
+     * Check if a tool exists
+     */
+    hasTool(toolName: string): boolean;
+}

package/dist/core/mcp/mcp-client.js

@@ -0,0 +1,6 @@
+var T=Object.defineProperty;var p=(c,t)=>T(c,"name",{value:t,configurable:!0});import{spawn as w}from"child_process";import{existsSync as v,readFileSync as $}from"fs";import{join as R}from"path";import{getAgentDir as E}from"../../config.js";import{AuthStorage as C}from"../platform/config/auth-storage.js";import{getMCPConfigPath as b}from"./mcp-config.js";const y=["1","true","yes","on"].includes((process.env.CATUI_DEBUG??"").toLowerCase());function g(...c){y&&console.error(...c)}p(g,"mcpLog");function F(...c){y&&console.warn(...c)}p(F,"mcpWarn");function x(...c){console.error(...c)}p(x,"mcpError");function M(c){if(c==null)return"Unknown error";if(c instanceof Error){const t=c.message?.trim();return t.length>0?t:c.name&&c.name!=="Error"?c.name:"Error (empty message)"}if(typeof c=="string")return c;try{return JSON.stringify(c)}catch{return String(c)}}p(M,"formatUnknownError");function P(c,t,e){const s=M(e);g(c==="http"?`[MCP] HTTP init failed ${t}: ${s}`:`[MCP] stdio start failed ${t}: ${s}`)}p(P,"logMcpStartupFailure");class O{static{p(this,"MCPClient")}servers=new Map;serverRuntimes=new Map;serverTools=new Map;httpSessions=new Map;authStorage;agentDir;mcpConfigPath;constructor(t,e,s){this.agentDir=e,this.mcpConfigPath=s;const n=t??R(e??E(),"auth.json");this.authStorage=C.create(n),this.loadServersFromConfig()}loadServersFromConfig(){const t=b(this.agentDir,this.mcpConfigPath);if(v(t))try{const s=JSON.parse($(t,"utf-8")).mcpServers||[];for(const n of s)n.enabled!==!1&&this.servers.set(n.id,n)}catch(e){x(`Failed to load MCP config: ${e}`)}}getServers(){return Array.from(this.servers.values())}getServer(t){return this.servers.get(t)}addServer(t){this.servers.set(t.id,t)}removeServer(t){this.servers.delete(t),this.serverTools.delete(t),this.stopServer(t)}getRuntime(t){return this.serverRuntimes.get(t)}convertNpxArgsToNpmExecArgs(t){if(t.length===0)return;const e=[...t];(e[0]==="-y"||e[0]==="--yes")&&e.shift();const s=e.shift();if(s)return["exec","--yes",s,...e.length>0?["--",...e]:[]]}getSpawnAttempts(t){if(!t.command)return[];const e=[],s=t.command.trim(),n=s.toLowerCase(),r=t.args??[];if(process.platform==="win32"&&n==="npx"){e.push({command:"npx.cmd",args:r});const o=this.convertNpxArgsToNpmExecArgs(r);return o&&e.push({command:"npm.cmd",args:o}),e.push({command:"npx",args:r}),e}if(e.push({command:s,args:r}),n==="npx"){const o=this.convertNpxArgsToNpmExecArgs(r);o&&e.push({command:process.platform==="win32"?"npm.cmd":"npm",args:o})}return e}async spawnProcess(t,e,s){return await new Promise((n,r)=>{const a=process.platform==="win32"?w([t.command,...t.args].map(u=>u.includes(" ")?`"${u}"`:u).join(" "),{env:e,cwd:s,stdio:["pipe","pipe","pipe"],windowsHide:!0,shell:!0}):w(t.command,t.args,{env:e,cwd:s,stdio:["pipe","pipe","pipe"],windowsHide:!0,shell:!1}),i=p(u=>{a.removeListener("spawn",l),r(u)},"onError"),l=p(()=>{a.removeListener("error",i),n(a)},"onSpawn");a.once("error",i),a.once("spawn",l)})}attachStdoutParser(t,e){const s=p(n=>{if(this.serverRuntimes.get(t)===e){for(const r of e.pendingRequests.values())clearTimeout(r.timer),r.reject(n);e.pendingRequests.clear(),this.serverRuntimes.delete(t)}},"rejectPending");e.process.stdin.on("error",n=>{const o=n.code==="EPIPE"?"process exited before MCP handshake (check command and npm package name)":n instanceof Error?n.message:String(n);g(`[MCP:${t}] stdin: ${o}`),s(new Error(`MCP server ${t} stdin closed: ${o}`))}),e.process.stdout.on("data",n=>{e.buffer=Buffer.concat([e.buffer,n]),this.processStdoutBuffer(t,e)}),e.process.stderr.on("data",n=>{const r=n.toString("utf8").trim();r.length>0&&y&&x(`[MCP:${t}] ${r}`)}),e.process.on("exit",(n,r)=>{if(this.serverRuntimes.get(t)!==e)return;const o=`[MCP:debug] Server exited: code=${n??"null"}, signal=${r??"null"}`;g(o),s(new Error(o))}),e.process.on("error",n=>{const r=`MCP server ${t} process error: ${n instanceof Error?n.message:String(n)}`;s(new Error(r))})}processStdoutBuffer(t,e){for(;e.buffer.length>0;){const s=e.buffer.indexOf(`
+`);if(s===-1)return;const n=e.buffer.slice(0,s).toString("utf8").replace(/\r$/,"");e.buffer=e.buffer.slice(s+1),n.length>0&&(g(`[MCP:${t}] Received: ${n.slice(0,200)}`),this.handleJsonRpcMessage(t,n))}}handleJsonRpcMessage(t,e){let s;try{s=JSON.parse(e)}catch{return}if(s.id===void 0)return;const n=typeof s.id=="number"?s.id:Number(s.id);if(!Number.isFinite(n))return;const r=this.serverRuntimes.get(t);if(!r)return;const o=r.pendingRequests.get(n);if(o){if(clearTimeout(o.timer),r.pendingRequests.delete(n),s.error){o.reject(new Error(s.error.message||`JSON-RPC error ${s.error.code??"unknown"}`));return}o.resolve(s.result)}}writeFramedMessage(t,e){const n=JSON.stringify(e)+`
+`;t.process.stdin.write(n)}sendNotification(t,e,s){const n=this.servers.get(t);if(n?.transport==="http"){this.sendHttpRequest(n,e,s,2e4,!0);return}const r=this.getRuntime(t);r&&this.writeFramedMessage(r,{jsonrpc:"2.0",method:e,params:s??{}})}async sendRequest(t,e,s,n=2e4){const r=this.servers.get(t);if(!r)throw new Error(`Server ${t} not found`);if(r.transport==="http")return await this.sendHttpRequest(r,e,s,n);const o=this.getRuntime(t);if(!o)throw new Error(`Server ${t} is not running`);const a=o.nextRequestId++,i={jsonrpc:"2.0",id:a,method:e,params:s??{}};return new Promise((l,u)=>{const h=setTimeout(()=>{o.pendingRequests.delete(a),u(new Error(`MCP request timed out: ${t} ${e} (${n}ms)`))},n);o.pendingRequests.set(a,{resolve:p(f=>l(f),"resolve"),reject:u,timer:h}),this.writeFramedMessage(o,i)})}getHttpSession(t){const e=this.httpSessions.get(t);if(e)return e;const s={initialized:!1};return this.httpSessions.set(t,s),s}async buildHttpHeaders(t,e){const s={"Content-Type":"application/json",Accept:"application/json, text/event-stream","MCP-Protocol-Version":"2025-03-26",...t.headers??{}};if(e&&(s["Mcp-Session-Id"]=e),t.authProvider){const n=await this.authStorage.getApiKey(t.authProvider);if(n){const r=t.authHeaderName?.trim()||"Authorization",o=t.authScheme??"bearer";s[r]=o==="raw"?n:`Bearer ${n}`}}return s}async ensureHttpInitialized(t){const e=this.getHttpSession(t.id);if(e.initialized)return;const s={protocolVersion:"2024-11-05",capabilities:{},clientInfo:{name:"catui-agent",version:"1.11.12"}};await this.sendHttpRequest(t,"initialize",s,t.initTimeout??2e4),e.initialized=!0,await this.sendHttpRequest(t,"notifications/initialized",{},t.initTimeout??2e4,!0)}async sendHttpRequest(t,e,s,n,r=!1,o=!0){if(!t.url)throw new Error(`HTTP MCP server ${t.id} is missing a url`);const a=this.getHttpSession(t.id);e!=="initialize"&&!a.initialized&&await this.ensureHttpInitialized(t);const i=r?void 0:Date.now()+Math.floor(Math.random()*1e3),l=r?{jsonrpc:"2.0",method:e,params:s??{}}:{jsonrpc:"2.0",id:i,method:e,params:s??{}},u=await fetch(t.url,{method:"POST",headers:await this.buildHttpHeaders(t,e==="initialize"?void 0:a.sessionId),body:JSON.stringify(l),signal:AbortSignal.timeout(n)});if(u.status===404&&a.sessionId&&o&&e!=="initialize")return this.httpSessions.set(t.id,{initialized:!1}),this.sendHttpRequest(t,e,s,n,r,!1);if(!u.ok){if(u.status===401&&t.authProvider)throw new Error(`HTTP MCP request failed (401 Unauthorized). The ${t.id} server requires valid credentials for "${t.authProvider}". Re-authenticate and try again.`);const S=await u.text().catch(()=>"");throw new Error(`HTTP MCP request failed (${u.status} ${u.statusText})${S?`: ${S}`:""}`)}const h=u.headers.get("Mcp-Session-Id");if(h&&(a.sessionId=h),r)return;const f=u.headers.get("content-type")??"",m=await u.text();if(!m.trim())return;let d;if(f.includes("text/event-stream"))d=this.parseEventStreamResponse(m);else{if(!f.includes("application/json")&&!m.trim().startsWith("{"))throw new Error(`Unsupported HTTP MCP response content type: ${f||"unknown"}`);d=JSON.parse(m)}if(d.error)throw new Error(d.error.message||`JSON-RPC error ${d.error.code??"unknown"}`);return d.result}parseEventStreamResponse(t){const e=[];let s={};for(const r of t.split(/\r?\n/)){if(!r.trim()){(s.data!==void 0||s.event!==void 0)&&(e.push(s),s={});continue}if(r.startsWith(":"))continue;const o=r.indexOf(":"),a=o===-1?r:r.slice(0,o),i=o===-1?"":r.slice(o+1).trimStart();a==="event"?s.event=i:a==="data"&&(s.data=s.data?`${s.data}
+${i}`:i)}(s.data!==void 0||s.event!==void 0)&&e.push(s);const n=[...e].reverse().find(r=>typeof r.data=="string"&&r.data.trim().length>0)?.data;if(!n)throw new Error("HTTP MCP event-stream response did not include a JSON payload");return JSON.parse(n)}async initializeServer(t){const e=this.servers.get(t),s=e?.command?.toLowerCase().includes("npx")??!1,r=process.platform==="win32"&&s?1500:500;await new Promise(l=>setTimeout(l,r));const o=e?.initTimeout??2e4,a={protocolVersion:"2024-11-05",capabilities:{},clientInfo:{name:"catui-agent",version:"1.7.0"}},i={protocolVersion:"2024-10-07",capabilities:{},clientInfo:{name:"catui-agent",version:"1.7.0"}};try{await this.sendRequest(t,"initialize",a,o)}catch{await this.sendRequest(t,"initialize",i,o)}this.sendNotification(t,"notifications/initialized")}normalizeToolRecord(t,e){if(!e||typeof e!="object")return null;const s=e,n=s.name,r=s.description;if(typeof n!="string"||typeof r!="string")return null;const o=s.inputSchema&&typeof s.inputSchema=="object"?s.inputSchema:{type:"object",properties:{},additionalProperties:!0};return{name:`${t}/${n}`,displayName:typeof s.title=="string"?s.title:typeof s.displayName=="string"?s.displayName:void 0,description:r,inputSchema:o,serverId:t}}async loadToolsForServer(t){const e=[];let s;for(;;){const n=await this.sendRequest(t,"tools/list",s?{cursor:s}:{},2e4),r=Array.isArray(n.tools)?n.tools:[];for(const a of r){const i=this.normalizeToolRecord(t,a);i&&e.push(i)}const o=typeof n.nextCursor=="string"?n.nextCursor:typeof n.cursor=="string"?n.cursor:void 0;if(!o||o===s)break;s=o}return this.serverTools.set(t,e),e}async startServer(t){const e=this.servers.get(t);if(!e)throw new Error(`Server ${t} not found`);if(e.transport==="http")try{return await this.ensureHttpInitialized(e),await this.loadToolsForServer(t),!0}catch(r){return P("http",t,r),!1}if(e.transport==="sse"||this.serverRuntimes.has(t))return!0;const s=this.getSpawnAttempts(e);let n;for(const r of s)try{const o=e.cwd||process.cwd(),i={process:await this.spawnProcess(r,{...process.env,...e.env},o),buffer:Buffer.alloc(0),nextRequestId:1,pendingRequests:new Map};return this.serverRuntimes.set(t,i),this.attachStdoutParser(t,i),await this.initializeServer(t),await this.loadToolsForServer(t),!0}catch(o){n=o,this.stopServer(t)}return P("stdio",t,n),!1}stopServer(t){const e=this.servers.get(t),s=this.httpSessions.get(t);e?.transport==="http"&&s?.sessionId&&e.url&&this.buildHttpHeaders(e,s.sessionId).then(r=>fetch(e.url,{method:"DELETE",headers:r})).catch(()=>{}),this.httpSessions.delete(t);const n=this.serverRuntimes.get(t);if(n){for(const r of n.pendingRequests.values())clearTimeout(r.timer),r.reject(new Error(`MCP server ${t} stopped`));n.pendingRequests.clear(),n.process.kill(),this.serverRuntimes.delete(t)}}stopAllServers(){const t=new Set([...this.serverRuntimes.keys(),...this.httpSessions.keys()]);for(const e of t)this.stopServer(e)}async listTools(t){const e=[];if(t){if(!this.serverTools.has(t))try{await this.loadToolsForServer(t)}catch{}const s=this.serverTools.get(t)||[];e.push(...s)}else for(const[s]of this.servers.entries()){if(!this.serverTools.has(s))try{await this.loadToolsForServer(s)}catch{}e.push(...this.serverTools.get(s)||[])}return e}async callTool(t,e,s){const[n,...r]=t.split("/"),o=r.join("/"),a=this.servers.get(n);if(!a)return{content:[{type:"text",text:`Server ${n} not found`}],error:`Server ${n} not found`};const i=s??a.toolTimeout??2e4;return a.transport==="sse"?this.callSSETool(a,o,e):a.transport==="http"?this.callHttpTool(a,o,e,i):this.callStdioTool(a,o,e,i)}async callHttpTool(t,e,s,n=2e4){try{const r=await this.sendRequest(t.id,"tools/call",{name:e,arguments:s},n),o=r.isError===!0,a=Array.isArray(r.content)?r.content.map(i=>({type:i.type==="image"||i.type==="resource"?i.type:"text",text:typeof i.text=="string"?i.text:typeof i.message=="string"?i.message:void 0,data:i})):[{type:"text",text:JSON.stringify(r)}];return{content:a,error:o?a.map(i=>i.text).filter(i=>!!i).join(`
+`)||`MCP tool ${e} failed`:void 0}}catch(r){return{content:[{type:"text",text:`Failed to call tool: ${r}`}],error:String(r)}}}async callStdioTool(t,e,s,n=2e4){if(!this.serverRuntimes.has(t.id))return{content:[{type:"text",text:`Server ${t.id} is not running`}],error:`Server ${t.id} is not running`};try{const r=await this.sendRequest(t.id,"tools/call",{name:e,arguments:s},n),o=r.isError===!0,a=Array.isArray(r.content)?r.content.map(i=>({type:i.type==="image"||i.type==="resource"?i.type:"text",text:typeof i.text=="string"?i.text:typeof i.message=="string"?i.message:void 0,data:i})):[{type:"text",text:JSON.stringify(r)}];return{content:a,error:o?a.map(i=>i.text).filter(i=>!!i).join(`
+`)||`MCP tool ${e} failed`:void 0}}catch(r){return{content:[{type:"text",text:`Failed to call tool: ${r}`}],error:String(r)}}}async callSSETool(t,e,s){return{content:[{type:"text",text:`SSE transport is not implemented yet for ${t.id}/${e}`}],error:"SSE transport not yet supported"}}hasTool(t){const[e]=t.split("/");return this.servers.has(e)}}export{O as MCPClient};