shortcutxl 0.2.0

package/agent-docs/examples/extensions/custom-compaction.ts

@@ -0,0 +1,126 @@
+/**
+ * Custom Compaction Extension
+ *
+ * Replaces the default compaction behavior with a full summary of the entire context.
+ * Instead of keeping the last 20k tokens of conversation turns, this extension:
+ * 1. Summarizes ALL messages (messagesToSummarize + turnPrefixMessages)
+ * 2. Discards all old turns completely, keeping only the summary
+ *
+ * This example also demonstrates using a different model (Gemini Flash) for summarization,
+ * which can be cheaper/faster than the main conversation model.
+ *
+ * Usage:
+ *   shortcut --extension examples/extensions/custom-compaction.ts
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+import { complete, convertToLlm, serializeConversation } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.on('session_before_compact', async (event, ctx) => {
+    ctx.ui.notify('Custom compaction extension triggered', 'info');
+
+    const { preparation, branchEntries: _, signal } = event;
+    const {
+      messagesToSummarize,
+      turnPrefixMessages,
+      tokensBefore,
+      firstKeptEntryId,
+      previousSummary
+    } = preparation;
+
+    // Use Gemini Flash for summarization (cheaper/faster than most conversation models)
+    const model = ctx.modelRegistry.find('google', 'gemini-2.5-flash');
+    if (!model) {
+      ctx.ui.notify(`Could not find Gemini Flash model, using default compaction`, 'warning');
+      return;
+    }
+
+    // Resolve API key for the summarization model
+    const apiKey = await ctx.modelRegistry.getApiKey(model);
+    if (!apiKey) {
+      ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, 'warning');
+      return;
+    }
+
+    // Combine all messages for full summary
+    const allMessages = [...messagesToSummarize, ...turnPrefixMessages];
+
+    ctx.ui.notify(
+      `Custom compaction: summarizing ${allMessages.length} messages (${tokensBefore.toLocaleString()} tokens) with ${model.id}...`,
+      'info'
+    );
+
+    // Convert messages to readable text format
+    const conversationText = serializeConversation(convertToLlm(allMessages));
+
+    // Include previous summary context if available
+    const previousContext = previousSummary
+      ? `\n\nPrevious session summary for context:\n${previousSummary}`
+      : '';
+
+    // Build messages that ask for a comprehensive summary
+    const summaryMessages = [
+      {
+        role: 'user' as const,
+        content: [
+          {
+            type: 'text' as const,
+            text: `You are a conversation summarizer. Create a comprehensive summary of this conversation that captures:${previousContext}
+
+1. The main goals and objectives discussed
+2. Key decisions made and their rationale
+3. Important code changes, file modifications, or technical details
+4. Current state of any ongoing work
+5. Any blockers, issues, or open questions
+6. Next steps that were planned or suggested
+
+Be thorough but concise. The summary will replace the ENTIRE conversation history, so include all information needed to continue the work effectively.
+
+Format the summary as structured markdown with clear sections.
+
+<conversation>
+${conversationText}
+</conversation>`
+          }
+        ],
+        timestamp: Date.now()
+      }
+    ];
+
+    try {
+      // Pass signal to honor abort requests (e.g., user cancels compaction)
+      const response = await complete(
+        model,
+        { messages: summaryMessages },
+        { apiKey, maxTokens: 8192, signal }
+      );
+
+      const summary = response.content
+        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+        .map((c) => c.text)
+        .join('\n');
+
+      if (!summary.trim()) {
+        if (!signal.aborted)
+          ctx.ui.notify('Compaction summary was empty, using default compaction', 'warning');
+        return;
+      }
+
+      // Return compaction content - SessionManager adds id/parentId
+      // Use firstKeptEntryId from preparation to keep recent messages
+      return {
+        compaction: {
+          summary,
+          firstKeptEntryId,
+          tokensBefore
+        }
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Compaction failed: ${message}`, 'error');
+      // Fall back to default compaction on error
+      return;
+    }
+  });
+}

package/agent-docs/examples/extensions/custom-footer.ts

@@ -0,0 +1,63 @@
+/**
+ * Custom Footer Extension - demonstrates ctx.ui.setFooter()
+ *
+ * footerData exposes data not otherwise accessible:
+ * - getGitBranch(): current git branch
+ * - getExtensionStatuses(): texts from ctx.ui.setStatus()
+ *
+ * Token stats come from ctx.sessionManager/ctx.model (already accessible).
+ */
+
+import type { AssistantMessage, ExtensionAPI } from 'shortcutxl';
+import { truncateToWidth, visibleWidth } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  let enabled = false;
+
+  shortcut.registerCommand('footer', {
+    description: 'Toggle custom footer',
+    handler: async (_args, ctx) => {
+      enabled = !enabled;
+
+      if (enabled) {
+        ctx.ui.setFooter((tui, theme, footerData) => {
+          const unsub = footerData.onBranchChange(() => tui.requestRender());
+
+          return {
+            dispose: unsub,
+            invalidate() {},
+            render(width: number): string[] {
+              // Compute tokens from ctx (already accessible to extensions)
+              let input = 0,
+                output = 0,
+                cost = 0;
+              for (const e of ctx.sessionManager.getBranch()) {
+                if (e.type === 'message' && e.message.role === 'assistant') {
+                  const m = e.message as AssistantMessage;
+                  input += m.usage.input;
+                  output += m.usage.output;
+                  cost += m.usage.cost.total;
+                }
+              }
+
+              // Get git branch (not otherwise accessible)
+              const branch = footerData.getGitBranch();
+              const fmt = (n: number) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(1)}k`);
+
+              const left = theme.fg('dim', `↑${fmt(input)} ↓${fmt(output)} $${cost.toFixed(3)}`);
+              const branchStr = branch ? ` (${branch})` : '';
+              const right = theme.fg('dim', `${ctx.model?.id || 'no-model'}${branchStr}`);
+
+              const pad = ' '.repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right)));
+              return [truncateToWidth(left + pad + right, width)];
+            }
+          };
+        });
+        ctx.ui.notify('Custom footer enabled', 'info');
+      } else {
+        ctx.ui.setFooter(undefined);
+        ctx.ui.notify('Default footer restored', 'info');
+      }
+    }
+  });
+}

package/agent-docs/examples/extensions/custom-header.ts

@@ -0,0 +1,73 @@
+/**
+ * Custom Header Extension
+ *
+ * Demonstrates ctx.ui.setHeader() for replacing the built-in header
+ * (logo + keybinding hints) with a custom component showing the shortcut mascot.
+ */
+
+import type { ExtensionAPI, Theme } from 'shortcutxl';
+import { VERSION } from 'shortcutxl';
+
+// --- PI MASCOT ---
+// Based on shortcut_mascot.ts - the shortcut agent character
+function getPiMascot(theme: Theme): string[] {
+  // --- COLORS ---
+  // 3b1b Blue: R=80, G=180, B=230
+  const piBlue = (text: string) => theme.fg('accent', text);
+  const white = (text: string) => text; // Use plain white (or theme.fg("text", text))
+  const black = (text: string) => theme.fg('dim', text); // Use dim for contrast
+
+  // --- GLYPHS ---
+  const BLOCK = '█';
+  const PUPIL = '▌'; // Vertical half-block for the pupil
+
+  // --- CONSTRUCTION ---
+
+  // 1. The Eye Unit: [White Full Block][Black Vertical Sliver]
+  // This creates the "looking sideways" effect
+  const eye = `${white(BLOCK)}${black(PUPIL)}`;
+
+  // 2. Line 1: The Eyes
+  // 5 spaces indent aligns them with the start of the legs
+  const lineEyes = `     ${eye}  ${eye}`;
+
+  // 3. Line 2: The Wide Top Bar (The "Overhang")
+  // 14 blocks wide for that serif-style roof
+  const lineBar = `  ${piBlue(BLOCK.repeat(14))}`;
+
+  // 4. Lines 3-6: The Legs
+  // Indented 5 spaces relative to the very left edge
+  // Leg width: 2 blocks | Gap: 4 blocks
+  const lineLeg = `     ${piBlue(BLOCK.repeat(2))}    ${piBlue(BLOCK.repeat(2))}`;
+
+  // --- ASSEMBLY ---
+  return ['', lineEyes, lineBar, lineLeg, lineLeg, lineLeg, lineLeg, ''];
+}
+
+export default function (shortcut: ExtensionAPI) {
+  // Set custom header immediately on load (if UI is available)
+  shortcut.on('session_start', async (_event, ctx) => {
+    if (ctx.hasUI) {
+      ctx.ui.setHeader((_tui, theme) => {
+        return {
+          render(_width: number): string[] {
+            const mascotLines = getPiMascot(theme);
+            // Add a subtitle with hint
+            const subtitle = `${theme.fg('muted', '   shitty coding agent')}${theme.fg('dim', ` v${VERSION}`)}`;
+            return [...mascotLines, subtitle];
+          },
+          invalidate() {}
+        };
+      });
+    }
+  });
+
+  // Command to restore built-in header
+  shortcut.registerCommand('builtin-header', {
+    description: 'Restore built-in header with keybinding hints',
+    handler: async (_args, ctx) => {
+      ctx.ui.setHeader(undefined);
+      ctx.ui.notify('Built-in header restored', 'info');
+    }
+  });
+}