shortcutxl 0.2.0

package/agent-docs/examples/rpc-extension-ui.ts

@@ -0,0 +1,654 @@
+/**
+ * RPC Extension UI Example (TUI)
+ *
+ * A lightweight TUI chat client that spawns the agent in RPC mode.
+ * Demonstrates how to build a custom UI on top of the RPC protocol,
+ * including handling extension UI requests (select, confirm, input, editor).
+ *
+ * Usage: npx tsx examples/rpc-extension-ui.ts
+ *
+ * Slash commands:
+ *   /select  - demo select dialog
+ *   /confirm - demo confirm dialog
+ *   /input   - demo input dialog
+ *   /editor  - demo editor dialog
+ */
+
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import * as readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import {
+  type Component,
+  Container,
+  Input,
+  matchesKey,
+  ProcessTerminal,
+  SelectList,
+  TUI
+} from 'shortcutxl';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ============================================================================
+// ANSI helpers
+// ============================================================================
+
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const BLUE = '\x1b[34m';
+const MAGENTA = '\x1b[35m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+// ============================================================================
+// Extension UI request type (subset of rpc-types.ts)
+// ============================================================================
+
+interface ExtensionUIRequest {
+  type: 'extension_ui_request';
+  id: string;
+  method: string;
+  title?: string;
+  options?: string[];
+  message?: string;
+  placeholder?: string;
+  prefill?: string;
+  notifyType?: 'info' | 'warning' | 'error';
+  statusKey?: string;
+  statusText?: string;
+  widgetKey?: string;
+  widgetLines?: string[];
+  text?: string;
+}
+
+// ============================================================================
+// Output log: accumulates styled lines, renders the tail that fits
+// ============================================================================
+
+class OutputLog implements Component {
+  private lines: string[] = [];
+  private maxLines = 1000;
+  private visibleLines = 0;
+
+  setVisibleLines(n: number): void {
+    this.visibleLines = n;
+  }
+
+  append(line: string): void {
+    this.lines.push(line);
+    if (this.lines.length > this.maxLines) {
+      this.lines = this.lines.slice(-this.maxLines);
+    }
+  }
+
+  appendRaw(text: string): void {
+    if (this.lines.length === 0) {
+      this.lines.push(text);
+    } else {
+      this.lines[this.lines.length - 1] += text;
+    }
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    if (this.lines.length === 0) return [''];
+    const n = this.visibleLines > 0 ? this.visibleLines : this.lines.length;
+    return this.lines.slice(-n).map((l) => l.slice(0, width));
+  }
+}
+
+// ============================================================================
+// Loading indicator: "Agent: Working." -> ".." -> "..." -> "."
+// ============================================================================
+
+class LoadingIndicator implements Component {
+  private dots = 1;
+  private intervalId: NodeJS.Timeout | null = null;
+  private tui: TUI | null = null;
+
+  start(tui: TUI): void {
+    this.tui = tui;
+    this.dots = 1;
+    this.intervalId = setInterval(() => {
+      this.dots = (this.dots % 3) + 1;
+      this.tui?.requestRender();
+    }, 400);
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  invalidate(): void {}
+
+  render(_width: number): string[] {
+    return [`${BLUE}${BOLD}Agent:${RESET} ${DIM}Working${'.'.repeat(this.dots)}${RESET}`];
+  }
+}
+
+// ============================================================================
+// Prompt input: label + single-line input
+// ============================================================================
+
+class PromptInput implements Component {
+  readonly input: Input;
+  onCtrlD?: () => void;
+
+  constructor() {
+    this.input = new Input();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, 'ctrl+d')) {
+      this.onCtrlD?.();
+      return;
+    }
+    this.input.handleInput(data);
+  }
+
+  invalidate(): void {
+    this.input.invalidate();
+  }
+
+  render(width: number): string[] {
+    return [`${GREEN}${BOLD}You:${RESET}`, ...this.input.render(width)];
+  }
+}
+
+// ============================================================================
+// Dialog components: replace the prompt input during interactive requests
+// ============================================================================
+
+class SelectDialog implements Component {
+  private list: SelectList;
+  private title: string;
+  onSelect?: (value: string) => void;
+  onCancel?: () => void;
+
+  constructor(title: string, options: string[]) {
+    this.title = title;
+    const items = options.map((o) => ({ value: o, label: o }));
+    this.list = new SelectList(items, Math.min(items.length, 8), {
+      selectedPrefix: (t) => `${MAGENTA}${t}${RESET}`,
+      selectedText: (t) => `${MAGENTA}${t}${RESET}`,
+      description: (t) => `${DIM}${t}${RESET}`,
+      scrollInfo: (t) => `${DIM}${t}${RESET}`,
+      noMatch: (t) => `${YELLOW}${t}${RESET}`
+    });
+    this.list.onSelect = (item) => this.onSelect?.(item.value);
+    this.list.onCancel = () => this.onCancel?.();
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+  }
+
+  invalidate(): void {
+    this.list.invalidate();
+  }
+
+  render(width: number): string[] {
+    return [
+      `${MAGENTA}${BOLD}${this.title}${RESET}`,
+      ...this.list.render(width),
+      `${DIM}Up/Down, Enter to select, Esc to cancel${RESET}`
+    ];
+  }
+}
+
+class InputDialog implements Component {
+  private dialogInput: Input;
+  private title: string;
+  onCtrlD?: () => void;
+
+  constructor(title: string, prefill?: string) {
+    this.title = title;
+    this.dialogInput = new Input();
+    if (prefill) this.dialogInput.setValue(prefill);
+  }
+
+  set onSubmit(fn: ((value: string) => void) | undefined) {
+    this.dialogInput.onSubmit = fn;
+  }
+
+  set onEscape(fn: (() => void) | undefined) {
+    this.dialogInput.onEscape = fn;
+  }
+
+  get inputComponent(): Input {
+    return this.dialogInput;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, 'ctrl+d')) {
+      this.onCtrlD?.();
+      return;
+    }
+    this.dialogInput.handleInput(data);
+  }
+
+  invalidate(): void {
+    this.dialogInput.invalidate();
+  }
+
+  render(width: number): string[] {
+    return [
+      `${MAGENTA}${BOLD}${this.title}${RESET}`,
+      ...this.dialogInput.render(width),
+      `${DIM}Enter to submit, Esc to cancel${RESET}`
+    ];
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  const extensionPath = join(__dirname, 'extensions/rpc-demo.ts');
+  const cliPath = join(__dirname, '../dist/cli.js');
+
+  const agent = spawn(
+    'node',
+    [cliPath, '--mode', 'rpc', '--no-session', '--no-extension', '--extension', extensionPath],
+    { stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+
+  let stderr = '';
+  agent.stderr?.on('data', (data: Buffer) => {
+    stderr += data.toString();
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  if (agent.exitCode !== null) {
+    console.error(`Agent exited immediately. Stderr:\n${stderr}`);
+    process.exit(1);
+  }
+
+  // -- TUI setup --
+
+  const terminal = new ProcessTerminal();
+  const tui = new TUI(terminal);
+
+  const outputLog = new OutputLog();
+  const loadingIndicator = new LoadingIndicator();
+  const promptInput = new PromptInput();
+
+  const root = new Container();
+  root.addChild(outputLog);
+  root.addChild(promptInput);
+
+  tui.addChild(root);
+  tui.setFocus(promptInput.input);
+
+  // -- Agent communication --
+
+  function send(obj: Record<string, unknown>): void {
+    agent.stdin!.write(`${JSON.stringify(obj)}\n`);
+  }
+
+  let isStreaming = false;
+  let hasTextOutput = false;
+
+  function exit(): void {
+    tui.stop();
+    agent.kill('SIGTERM');
+    process.exit(0);
+  }
+
+  // -- Bottom area management --
+  // The bottom of the screen is either the prompt input or a dialog.
+  // These helpers swap between them.
+
+  let activeDialog: Component | null = null;
+
+  function setBottomComponent(component: Component): void {
+    root.clear();
+    root.addChild(outputLog);
+    if (isStreaming) root.addChild(loadingIndicator);
+    root.addChild(component);
+    tui.setFocus(component);
+    tui.requestRender();
+  }
+
+  function showPrompt(): void {
+    activeDialog = null;
+    setBottomComponent(promptInput);
+    tui.setFocus(promptInput.input);
+  }
+
+  function showDialog(dialog: Component): void {
+    activeDialog = dialog;
+    setBottomComponent(dialog);
+  }
+
+  function showLoading(): void {
+    if (!isStreaming) {
+      isStreaming = true;
+      hasTextOutput = false;
+      root.clear();
+      root.addChild(outputLog);
+      root.addChild(loadingIndicator);
+      root.addChild(activeDialog ?? promptInput);
+      if (!activeDialog) tui.setFocus(promptInput.input);
+      loadingIndicator.start(tui);
+      tui.requestRender();
+    }
+  }
+
+  function hideLoading(): void {
+    loadingIndicator.stop();
+    root.clear();
+    root.addChild(outputLog);
+    root.addChild(activeDialog ?? promptInput);
+    if (!activeDialog) tui.setFocus(promptInput.input);
+    tui.requestRender();
+  }
+
+  // -- Extension UI dialog handling --
+
+  function showSelectDialog(
+    title: string,
+    options: string[],
+    onDone: (value: string | undefined) => void
+  ): void {
+    const dialog = new SelectDialog(title, options);
+    dialog.onSelect = (value) => {
+      showPrompt();
+      onDone(value);
+    };
+    dialog.onCancel = () => {
+      showPrompt();
+      onDone(undefined);
+    };
+    showDialog(dialog);
+  }
+
+  function showInputDialog(
+    title: string,
+    prefill?: string,
+    onDone?: (value: string | undefined) => void
+  ): void {
+    const dialog = new InputDialog(title, prefill);
+    dialog.onSubmit = (value) => {
+      showPrompt();
+      onDone?.(value.trim() || undefined);
+    };
+    dialog.onEscape = () => {
+      showPrompt();
+      onDone?.(undefined);
+    };
+    dialog.onCtrlD = exit;
+    showDialog(dialog);
+    tui.setFocus(dialog.inputComponent);
+  }
+
+  function handleExtensionUI(req: ExtensionUIRequest): void {
+    const { id, method } = req;
+
+    switch (method) {
+      // Dialog methods: replace prompt with interactive component
+      case 'select': {
+        showSelectDialog(req.title ?? 'Select', req.options ?? [], (value) => {
+          if (value !== undefined) {
+            send({ type: 'extension_ui_response', id, value });
+          } else {
+            send({ type: 'extension_ui_response', id, cancelled: true });
+          }
+        });
+        break;
+      }
+
+      case 'confirm': {
+        const title = req.message ? `${req.title}: ${req.message}` : (req.title ?? 'Confirm');
+        showSelectDialog(title, ['Yes', 'No'], (value) => {
+          send({ type: 'extension_ui_response', id, confirmed: value === 'Yes' });
+        });
+        break;
+      }
+
+      case 'input': {
+        const title = req.placeholder
+          ? `${req.title} (${req.placeholder})`
+          : (req.title ?? 'Input');
+        showInputDialog(title, undefined, (value) => {
+          if (value !== undefined) {
+            send({ type: 'extension_ui_response', id, value });
+          } else {
+            send({ type: 'extension_ui_response', id, cancelled: true });
+          }
+        });
+        break;
+      }
+
+      case 'editor': {
+        const prefill = req.prefill?.replace(/\n/g, ' ');
+        showInputDialog(req.title ?? 'Editor', prefill, (value) => {
+          if (value !== undefined) {
+            send({ type: 'extension_ui_response', id, value });
+          } else {
+            send({ type: 'extension_ui_response', id, cancelled: true });
+          }
+        });
+        break;
+      }
+
+      // Fire-and-forget methods: display as notification
+      case 'notify': {
+        const notifyType = (req.notifyType as string) ?? 'info';
+        const color = notifyType === 'error' ? RED : notifyType === 'warning' ? YELLOW : MAGENTA;
+        outputLog.append(`${color}${BOLD}Notification:${RESET} ${req.message}`);
+        tui.requestRender();
+        break;
+      }
+
+      case 'setStatus':
+        outputLog.append(
+          `${MAGENTA}${BOLD}Notification:${RESET} ${DIM}[status: ${req.statusKey}]${RESET} ${req.statusText ?? '(cleared)'}`
+        );
+        tui.requestRender();
+        break;
+
+      case 'setWidget': {
+        const lines = req.widgetLines;
+        if (lines && lines.length > 0) {
+          outputLog.append(
+            `${MAGENTA}${BOLD}Notification:${RESET} ${DIM}[widget: ${req.widgetKey}]${RESET}`
+          );
+          for (const wl of lines) {
+            outputLog.append(`  ${DIM}${wl}${RESET}`);
+          }
+          tui.requestRender();
+        }
+        break;
+      }
+
+      case 'set_editor_text':
+        promptInput.input.setValue((req.text as string) ?? '');
+        tui.requestRender();
+        break;
+    }
+  }
+
+  // -- Slash commands (local, not sent to agent) --
+
+  function handleSlashCommand(cmd: string): boolean {
+    switch (cmd) {
+      case '/select':
+        showSelectDialog('Pick a color', ['Red', 'Green', 'Blue', 'Yellow'], (value) => {
+          if (value) {
+            outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} You picked: ${value}`);
+          } else {
+            outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} Selection cancelled`);
+          }
+          tui.requestRender();
+        });
+        return true;
+
+      case '/confirm':
+        showSelectDialog('Are you sure?', ['Yes', 'No'], (value) => {
+          const confirmed = value === 'Yes';
+          outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} Confirmed: ${confirmed}`);
+          tui.requestRender();
+        });
+        return true;
+
+      case '/input':
+        showInputDialog('Enter your name', undefined, (value) => {
+          if (value) {
+            outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} You entered: ${value}`);
+          } else {
+            outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} Input cancelled`);
+          }
+          tui.requestRender();
+        });
+        return true;
+
+      case '/editor':
+        showInputDialog('Edit text', 'Hello, world!', (value) => {
+          if (value) {
+            outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} Submitted: ${value}`);
+          } else {
+            outputLog.append(`${MAGENTA}${BOLD}Notification:${RESET} Editor cancelled`);
+          }
+          tui.requestRender();
+        });
+        return true;
+
+      default:
+        return false;
+    }
+  }
+
+  // -- Process agent stdout --
+
+  const stdoutRl = readline.createInterface({ input: agent.stdout!, terminal: false });
+
+  stdoutRl.on('line', (line) => {
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    if (data.type === 'response' && !data.success) {
+      outputLog.append(`${RED}[error]${RESET} ${data.command}: ${data.error}`);
+      tui.requestRender();
+      return;
+    }
+
+    if (data.type === 'agent_start') {
+      showLoading();
+      return;
+    }
+
+    if (data.type === 'extension_ui_request') {
+      handleExtensionUI(data as unknown as ExtensionUIRequest);
+      return;
+    }
+
+    if (data.type === 'message_update') {
+      const evt = data.assistantMessageEvent as Record<string, unknown> | undefined;
+      if (evt?.type === 'text_delta') {
+        if (!hasTextOutput) {
+          hasTextOutput = true;
+          outputLog.append('');
+          outputLog.append(`${BLUE}${BOLD}Agent:${RESET}`);
+        }
+        const delta = evt.delta as string;
+        const parts = delta.split('\n');
+        for (let i = 0; i < parts.length; i++) {
+          if (i > 0) outputLog.append('');
+          if (parts[i]) outputLog.appendRaw(parts[i]);
+        }
+        tui.requestRender();
+      }
+      return;
+    }
+
+    if (data.type === 'tool_execution_start') {
+      outputLog.append(`${DIM}[tool: ${data.toolName}]${RESET}`);
+      tui.requestRender();
+      return;
+    }
+
+    if (data.type === 'tool_execution_end') {
+      const result = JSON.stringify(data.result).slice(0, 120);
+      outputLog.append(`${DIM}[result: ${result}...]${RESET}`);
+      tui.requestRender();
+      return;
+    }
+
+    if (data.type === 'agent_end') {
+      isStreaming = false;
+      hideLoading();
+      outputLog.append('');
+      tui.requestRender();
+      return;
+    }
+  });
+
+  // -- User input --
+
+  promptInput.input.onSubmit = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed) return;
+
+    promptInput.input.setValue('');
+
+    if (handleSlashCommand(trimmed)) {
+      outputLog.append(`${GREEN}${BOLD}You:${RESET} ${trimmed}`);
+      tui.requestRender();
+      return;
+    }
+
+    outputLog.append(`${GREEN}${BOLD}You:${RESET} ${trimmed}`);
+    send({ type: 'prompt', message: trimmed });
+    tui.requestRender();
+  };
+
+  promptInput.onCtrlD = exit;
+
+  promptInput.input.onEscape = () => {
+    if (isStreaming) {
+      send({ type: 'abort' });
+      outputLog.append(`${YELLOW}[aborted]${RESET}`);
+      tui.requestRender();
+    } else {
+      exit();
+    }
+  };
+
+  // -- Agent exit --
+
+  agent.on('exit', (code) => {
+    tui.stop();
+    if (stderr) console.error(stderr);
+    console.log(`Agent exited with code ${code}`);
+    process.exit(code ?? 0);
+  });
+
+  // -- Start --
+
+  outputLog.append(`${BOLD}RPC Chat${RESET}`);
+  outputLog.append(
+    `${DIM}Type a message and press Enter. Esc to abort or exit. Ctrl+D to quit.${RESET}`
+  );
+  outputLog.append(`${DIM}Slash commands: /select /confirm /input /editor${RESET}`);
+  outputLog.append('');
+
+  tui.start();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/agent-docs/examples/sdk/01-minimal.ts

@@ -0,0 +1,22 @@
+/**
+ * Minimal SDK Usage
+ *
+ * Uses all defaults: discovers skills, extensions, tools, context files
+ * from cwd and ~/.shortcut/agent. Model chosen from settings or first available.
+ */
+
+import { createAgentSession } from 'shortcutxl';
+
+const { session } = await createAgentSession();
+
+session.subscribe((event) => {
+  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt('What files are in the current directory?');
+session.state.messages.forEach((msg) => {
+  console.log(msg);
+});
+console.log();