shortcutxl 0.2.0

package/agent-docs/examples/extensions/qna.ts

@@ -0,0 +1,122 @@
+/**
+ * Q&A extraction extension - extracts questions from assistant responses
+ *
+ * Demonstrates the "prompt generator" pattern:
+ * 1. /qna command gets the last assistant message
+ * 2. Shows a spinner while extracting (hides editor)
+ * 3. Loads the result into the editor for user to fill in answers
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+import { BorderedLoader, complete, type UserMessage } from 'shortcutxl';
+
+const SYSTEM_PROMPT = `You are a question extractor. Given text from a conversation, extract any questions that need answering and format them for the user to fill in.
+
+Output format:
+- List each question on its own line, prefixed with "Q: "
+- After each question, add a blank line for the answer prefixed with "A: "
+- If no questions are found, output "No questions found in the last message."
+
+Example output:
+Q: What is your preferred database?
+A: 
+
+Q: Should we use TypeScript or JavaScript?
+A: 
+
+Keep questions in the order they appeared. Be concise.`;
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerCommand('qna', {
+    description: 'Extract questions from last assistant message into editor',
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify('qna requires interactive mode', 'error');
+        return;
+      }
+
+      if (!ctx.model) {
+        ctx.ui.notify('No model selected', 'error');
+        return;
+      }
+
+      // Find the last assistant message on the current branch
+      const branch = ctx.sessionManager.getBranch();
+      let lastAssistantText: string | undefined;
+
+      for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry.type === 'message') {
+          const msg = entry.message;
+          if ('role' in msg && msg.role === 'assistant') {
+            if (msg.stopReason !== 'stop') {
+              ctx.ui.notify(`Last assistant message incomplete (${msg.stopReason})`, 'error');
+              return;
+            }
+            const textParts = msg.content
+              .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+              .map((c) => c.text);
+            if (textParts.length > 0) {
+              lastAssistantText = textParts.join('\n');
+              break;
+            }
+          }
+        }
+      }
+
+      if (!lastAssistantText) {
+        ctx.ui.notify('No assistant messages found', 'error');
+        return;
+      }
+
+      // Run extraction with loader UI
+      const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+        const loader = new BorderedLoader(
+          tui,
+          theme,
+          `Extracting questions using ${ctx.model!.id}...`
+        );
+        loader.onAbort = () => done(null);
+
+        // Do the work
+        const doExtract = async () => {
+          const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+          const userMessage: UserMessage = {
+            role: 'user',
+            content: [{ type: 'text', text: lastAssistantText! }],
+            timestamp: Date.now()
+          };
+
+          const response = await complete(
+            ctx.model!,
+            { systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+            { apiKey, signal: loader.signal }
+          );
+
+          if (response.stopReason === 'aborted') {
+            return null;
+          }
+
+          return response.content
+            .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+            .map((c) => c.text)
+            .join('\n');
+        };
+
+        doExtract()
+          .then(done)
+          .catch(() => done(null));
+
+        return loader;
+      });
+
+      if (result === null) {
+        ctx.ui.notify('Cancelled', 'info');
+        return;
+      }
+
+      ctx.ui.setEditorText(result);
+      ctx.ui.notify('Questions loaded. Edit and submit when ready.', 'info');
+    }
+  });
+}

package/agent-docs/examples/extensions/question.ts

@@ -0,0 +1,278 @@
+/**
+ * Question Tool - Single question with options
+ * Full custom UI: options list + inline editor for "Type something..."
+ * Escape in editor returns to options, Escape in options cancels
+ */
+
+import { Type } from '@sinclair/typebox';
+import type { ExtensionAPI } from 'shortcutxl';
+import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from 'shortcutxl';
+
+interface OptionWithDesc {
+  label: string;
+  description?: string;
+}
+
+type DisplayOption = OptionWithDesc & { isOther?: boolean };
+
+interface QuestionDetails {
+  question: string;
+  options: string[];
+  answer: string | null;
+  wasCustom?: boolean;
+}
+
+// Options with labels and optional descriptions
+const OptionSchema = Type.Object({
+  label: Type.String({ description: 'Display label for the option' }),
+  description: Type.Optional(Type.String({ description: 'Optional description shown below label' }))
+});
+
+const QuestionParams = Type.Object({
+  question: Type.String({ description: 'The question to ask the user' }),
+  options: Type.Array(OptionSchema, { description: 'Options for the user to choose from' })
+});
+
+export default function question(shortcut: ExtensionAPI) {
+  shortcut.registerTool({
+    name: 'question',
+    label: 'Question',
+    description:
+      'Ask the user a question and let them pick from options. Use when you need user input to proceed.',
+    parameters: QuestionParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (!ctx.hasUI) {
+        return {
+          content: [
+            { type: 'text', text: 'Error: UI not available (running in non-interactive mode)' }
+          ],
+          details: {
+            question: params.question,
+            options: params.options.map((o) => o.label),
+            answer: null
+          } as QuestionDetails
+        };
+      }
+
+      if (params.options.length === 0) {
+        return {
+          content: [{ type: 'text', text: 'Error: No options provided' }],
+          details: { question: params.question, options: [], answer: null } as QuestionDetails
+        };
+      }
+
+      const allOptions: DisplayOption[] = [
+        ...params.options,
+        { label: 'Type something.', isOther: true }
+      ];
+
+      const result = await ctx.ui.custom<{
+        answer: string;
+        wasCustom: boolean;
+        index?: number;
+      } | null>((tui, theme, _kb, done) => {
+        let optionIndex = 0;
+        let editMode = false;
+        let cachedLines: string[] | undefined;
+
+        const editorTheme: EditorTheme = {
+          borderColor: (s) => theme.fg('accent', s),
+          selectList: {
+            selectedPrefix: (t) => theme.fg('accent', t),
+            selectedText: (t) => theme.fg('accent', t),
+            description: (t) => theme.fg('muted', t),
+            scrollInfo: (t) => theme.fg('dim', t),
+            noMatch: (t) => theme.fg('warning', t)
+          }
+        };
+        const editor = new Editor(tui, editorTheme);
+
+        editor.onSubmit = (value) => {
+          const trimmed = value.trim();
+          if (trimmed) {
+            done({ answer: trimmed, wasCustom: true });
+          } else {
+            editMode = false;
+            editor.setText('');
+            refresh();
+          }
+        };
+
+        function refresh() {
+          cachedLines = undefined;
+          tui.requestRender();
+        }
+
+        function handleInput(data: string) {
+          if (editMode) {
+            if (matchesKey(data, Key.escape)) {
+              editMode = false;
+              editor.setText('');
+              refresh();
+              return;
+            }
+            editor.handleInput(data);
+            refresh();
+            return;
+          }
+
+          if (matchesKey(data, Key.up)) {
+            optionIndex = Math.max(0, optionIndex - 1);
+            refresh();
+            return;
+          }
+          if (matchesKey(data, Key.down)) {
+            optionIndex = Math.min(allOptions.length - 1, optionIndex + 1);
+            refresh();
+            return;
+          }
+
+          if (matchesKey(data, Key.enter)) {
+            const selected = allOptions[optionIndex];
+            if (selected.isOther) {
+              editMode = true;
+              refresh();
+            } else {
+              done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 });
+            }
+            return;
+          }
+
+          if (matchesKey(data, Key.escape)) {
+            done(null);
+          }
+        }
+
+        function render(width: number): string[] {
+          if (cachedLines) return cachedLines;
+
+          const lines: string[] = [];
+          const add = (s: string) => lines.push(truncateToWidth(s, width));
+
+          add(theme.fg('accent', '─'.repeat(width)));
+          add(theme.fg('text', ` ${params.question}`));
+          lines.push('');
+
+          for (let i = 0; i < allOptions.length; i++) {
+            const opt = allOptions[i];
+            const selected = i === optionIndex;
+            const isOther = opt.isOther === true;
+            const prefix = selected ? theme.fg('accent', '> ') : '  ';
+
+            if (isOther && editMode) {
+              add(prefix + theme.fg('accent', `${i + 1}. ${opt.label} ✎`));
+            } else if (selected) {
+              add(prefix + theme.fg('accent', `${i + 1}. ${opt.label}`));
+            } else {
+              add(`  ${theme.fg('text', `${i + 1}. ${opt.label}`)}`);
+            }
+
+            // Show description if present
+            if (opt.description) {
+              add(`     ${theme.fg('muted', opt.description)}`);
+            }
+          }
+
+          if (editMode) {
+            lines.push('');
+            add(theme.fg('muted', ' Your answer:'));
+            for (const line of editor.render(width - 2)) {
+              add(` ${line}`);
+            }
+          }
+
+          lines.push('');
+          if (editMode) {
+            add(theme.fg('dim', ' Enter to submit • Esc to go back'));
+          } else {
+            add(theme.fg('dim', ' ↑↓ navigate • Enter to select • Esc to cancel'));
+          }
+          add(theme.fg('accent', '─'.repeat(width)));
+
+          cachedLines = lines;
+          return lines;
+        }
+
+        return {
+          render,
+          invalidate: () => {
+            cachedLines = undefined;
+          },
+          handleInput
+        };
+      });
+
+      // Build simple options list for details
+      const simpleOptions = params.options.map((o) => o.label);
+
+      if (!result) {
+        return {
+          content: [{ type: 'text', text: 'User cancelled the selection' }],
+          details: {
+            question: params.question,
+            options: simpleOptions,
+            answer: null
+          } as QuestionDetails
+        };
+      }
+
+      if (result.wasCustom) {
+        return {
+          content: [{ type: 'text', text: `User wrote: ${result.answer}` }],
+          details: {
+            question: params.question,
+            options: simpleOptions,
+            answer: result.answer,
+            wasCustom: true
+          } as QuestionDetails
+        };
+      }
+      return {
+        content: [{ type: 'text', text: `User selected: ${result.index}. ${result.answer}` }],
+        details: {
+          question: params.question,
+          options: simpleOptions,
+          answer: result.answer,
+          wasCustom: false
+        } as QuestionDetails
+      };
+    },
+
+    renderCall(args, theme) {
+      let text = theme.fg('toolTitle', theme.bold('question ')) + theme.fg('muted', args.question);
+      const opts = Array.isArray(args.options) ? args.options : [];
+      if (opts.length) {
+        const labels = opts.map((o: OptionWithDesc) => o.label);
+        const numbered = [...labels, 'Type something.'].map((o, i) => `${i + 1}. ${o}`);
+        text += `\n${theme.fg('dim', `  Options: ${numbered.join(', ')}`)}`;
+      }
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as QuestionDetails | undefined;
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === 'text' ? text.text : '', 0, 0);
+      }
+
+      if (details.answer === null) {
+        return new Text(theme.fg('warning', 'Cancelled'), 0, 0);
+      }
+
+      if (details.wasCustom) {
+        return new Text(
+          theme.fg('success', '✓ ') +
+            theme.fg('muted', '(wrote) ') +
+            theme.fg('accent', details.answer),
+          0,
+          0
+        );
+      }
+      const idx = details.options.indexOf(details.answer) + 1;
+      const display = idx > 0 ? `${idx}. ${details.answer}` : details.answer;
+      return new Text(theme.fg('success', '✓ ') + theme.fg('accent', display), 0, 0);
+    }
+  });
+}