shortcutxl 0.2.12 → 0.2.13

package/agent-docs/examples/extensions/doom-overlay/index.ts

@@ -1,74 +1,74 @@
-/**
- * DOOM Overlay Demo - Play DOOM as an overlay
- *
- * Usage: shortcut --extension ./examples/extensions/doom-overlay
- *
- * Commands:
- *   /doom-overlay - Play DOOM in an overlay (Q to pause/exit)
- *
- * This demonstrates that overlays can handle real-time game rendering at 35 FPS.
- */
-
-import type { ExtensionAPI } from 'shortcutxl';
-import { DoomOverlayComponent } from './doom-component.js';
-import { DoomEngine } from './doom-engine.js';
-import { ensureWadFile } from './wad-finder.js';
-
-// Persistent engine instance - survives between invocations
-let activeEngine: DoomEngine | null = null;
-let activeWadPath: string | null = null;
-
-export default function (shortcut: ExtensionAPI) {
-  shortcut.registerCommand('doom-overlay', {
-    description: 'Play DOOM as an overlay. Q to pause and exit.',
-
-    handler: async (args, ctx) => {
-      if (!ctx.hasUI) {
-        ctx.ui.notify('DOOM requires interactive mode', 'error');
-        return;
-      }
-
-      // Auto-download WAD if not present
-      ctx.ui.notify('Loading DOOM...', 'info');
-      const wad = args?.trim() ? args.trim() : await ensureWadFile();
-
-      if (!wad) {
-        ctx.ui.notify('Failed to download DOOM WAD file. Check your internet connection.', 'error');
-        return;
-      }
-
-      try {
-        // Reuse existing engine if same WAD, otherwise create new
-        let isResume = false;
-        if (activeEngine && activeWadPath === wad) {
-          ctx.ui.notify('Resuming DOOM...', 'info');
-          isResume = true;
-        } else {
-          ctx.ui.notify(`Loading DOOM from ${wad}...`, 'info');
-          activeEngine = new DoomEngine(wad);
-          await activeEngine.init();
-          activeWadPath = wad;
-        }
-
-        await ctx.ui.custom(
-          (tui, _theme, _keybindings, done) => {
-            return new DoomOverlayComponent(tui, activeEngine!, () => done(undefined), isResume);
-          },
-          {
-            overlay: true,
-            overlayOptions: {
-              width: '75%',
-              maxHeight: '95%',
-              anchor: 'center',
-              margin: { top: 1 }
-            }
-          }
-        );
-      } catch (error) {
-        ctx.ui.notify(`Failed to load DOOM: ${error}`, 'error');
-        activeEngine = null;
-        activeWadPath = null;
-      }
-    }
-  });
-}
+/**
+ * DOOM Overlay Demo - Play DOOM as an overlay
+ *
+ * Usage: shortcut --extension ./examples/extensions/doom-overlay
+ *
+ * Commands:
+ *   /doom-overlay - Play DOOM in an overlay (Q to pause/exit)
+ *
+ * This demonstrates that overlays can handle real-time game rendering at 35 FPS.
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+import { DoomOverlayComponent } from './doom-component.js';
+import { DoomEngine } from './doom-engine.js';
+import { ensureWadFile } from './wad-finder.js';
+
+// Persistent engine instance - survives between invocations
+let activeEngine: DoomEngine | null = null;
+let activeWadPath: string | null = null;
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerCommand('doom-overlay', {
+    description: 'Play DOOM as an overlay. Q to pause and exit.',
+
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify('DOOM requires interactive mode', 'error');
+        return;
+      }
+
+      // Auto-download WAD if not present
+      ctx.ui.notify('Loading DOOM...', 'info');
+      const wad = args?.trim() ? args.trim() : await ensureWadFile();
+
+      if (!wad) {
+        ctx.ui.notify('Failed to download DOOM WAD file. Check your internet connection.', 'error');
+        return;
+      }
+
+      try {
+        // Reuse existing engine if same WAD, otherwise create new
+        let isResume = false;
+        if (activeEngine && activeWadPath === wad) {
+          ctx.ui.notify('Resuming DOOM...', 'info');
+          isResume = true;
+        } else {
+          ctx.ui.notify(`Loading DOOM from ${wad}...`, 'info');
+          activeEngine = new DoomEngine(wad);
+          await activeEngine.init();
+          activeWadPath = wad;
+        }
+
+        await ctx.ui.custom(
+          (tui, _theme, _keybindings, done) => {
+            return new DoomOverlayComponent(tui, activeEngine!, () => done(undefined), isResume);
+          },
+          {
+            overlay: true,
+            overlayOptions: {
+              width: '75%',
+              maxHeight: '95%',
+              anchor: 'center',
+              margin: { top: 1 }
+            }
+          }
+        );
+      } catch (error) {
+        ctx.ui.notify(`Failed to load DOOM: ${error}`, 'error');
+        activeEngine = null;
+        activeWadPath = null;
+      }
+    }
+  });
+}

package/agent-docs/examples/extensions/dynamic-resources/index.ts

@@ -1,15 +1,15 @@
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { ExtensionAPI } from 'shortcutxl';
-
-const baseDir = dirname(fileURLToPath(import.meta.url));
-
-export default function (shortcut: ExtensionAPI) {
-  shortcut.on('resources_discover', () => {
-    return {
-      skillPaths: [join(baseDir, 'SKILL.md')],
-      promptPaths: [join(baseDir, 'dynamic.md')],
-      themePaths: [join(baseDir, 'dynamic.json')]
-    };
-  });
-}
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ExtensionAPI } from 'shortcutxl';
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.on('resources_discover', () => {
+    return {
+      skillPaths: [join(baseDir, 'SKILL.md')],
+      promptPaths: [join(baseDir, 'dynamic.md')],
+      themePaths: [join(baseDir, 'dynamic.json')]
+    };
+  });
+}

package/agent-docs/examples/extensions/dynamic-tools.ts

@@ -1,77 +1,77 @@
-/**
- * Dynamic Tools Extension
- *
- * Demonstrates registering tools after session initialization.
- *
- * - Registers one tool during session_start
- * - Registers additional tools at runtime via /add-echo-tool <name>
- */
-
-import { Type } from '@sinclair/typebox';
-import type { ExtensionAPI } from 'shortcutxl';
-
-const ECHO_PARAMS = Type.Object({
-  message: Type.String({ description: 'Message to echo' })
-});
-
-function normalizeToolName(input: string): string | undefined {
-  const trimmed = input.trim().toLowerCase();
-  if (!trimmed) return undefined;
-  if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
-  return trimmed;
-}
-
-export default function dynamicToolsExtension(shortcut: ExtensionAPI) {
-  const registeredToolNames = new Set<string>();
-
-  const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
-    if (registeredToolNames.has(name)) {
-      return false;
-    }
-
-    registeredToolNames.add(name);
-    shortcut.registerTool({
-      name,
-      label,
-      description: `Echo a message with prefix: ${prefix}`,
-      promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
-      promptGuidelines: ['Use this tool when the user asks for exact echo output.'],
-      parameters: ECHO_PARAMS,
-      async execute(_toolCallId, params) {
-        return {
-          content: [{ type: 'text', text: `${prefix}${params.message}` }],
-          details: { tool: name, prefix }
-        };
-      }
-    });
-
-    return true;
-  };
-
-  shortcut.on('session_start', (_event, ctx) => {
-    registerEchoTool('echo_session', 'Echo Session', '[session] ');
-    ctx.ui.notify('Registered dynamic tool: echo_session', 'info');
-  });
-
-  shortcut.registerCommand('add-echo-tool', {
-    description: 'Register a new echo tool dynamically: /add-echo-tool <tool_name>',
-    handler: async (args, ctx) => {
-      const toolName = normalizeToolName(args);
-      if (!toolName) {
-        ctx.ui.notify(
-          'Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)',
-          'warning'
-        );
-        return;
-      }
-
-      const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
-      if (!created) {
-        ctx.ui.notify(`Tool already registered: ${toolName}`, 'warning');
-        return;
-      }
-
-      ctx.ui.notify(`Registered dynamic tool: ${toolName}`, 'info');
-    }
-  });
-}
+/**
+ * Dynamic Tools Extension
+ *
+ * Demonstrates registering tools after session initialization.
+ *
+ * - Registers one tool during session_start
+ * - Registers additional tools at runtime via /add-echo-tool <name>
+ */
+
+import { Type } from '@sinclair/typebox';
+import type { ExtensionAPI } from 'shortcutxl';
+
+const ECHO_PARAMS = Type.Object({
+  message: Type.String({ description: 'Message to echo' })
+});
+
+function normalizeToolName(input: string): string | undefined {
+  const trimmed = input.trim().toLowerCase();
+  if (!trimmed) return undefined;
+  if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
+  return trimmed;
+}
+
+export default function dynamicToolsExtension(shortcut: ExtensionAPI) {
+  const registeredToolNames = new Set<string>();
+
+  const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
+    if (registeredToolNames.has(name)) {
+      return false;
+    }
+
+    registeredToolNames.add(name);
+    shortcut.registerTool({
+      name,
+      label,
+      description: `Echo a message with prefix: ${prefix}`,
+      promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
+      promptGuidelines: ['Use this tool when the user asks for exact echo output.'],
+      parameters: ECHO_PARAMS,
+      async execute(_toolCallId, params) {
+        return {
+          content: [{ type: 'text', text: `${prefix}${params.message}` }],
+          details: { tool: name, prefix }
+        };
+      }
+    });
+
+    return true;
+  };
+
+  shortcut.on('session_start', (_event, ctx) => {
+    registerEchoTool('echo_session', 'Echo Session', '[session] ');
+    ctx.ui.notify('Registered dynamic tool: echo_session', 'info');
+  });
+
+  shortcut.registerCommand('add-echo-tool', {
+    description: 'Register a new echo tool dynamically: /add-echo-tool <tool_name>',
+    handler: async (args, ctx) => {
+      const toolName = normalizeToolName(args);
+      if (!toolName) {
+        ctx.ui.notify(
+          'Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)',
+          'warning'
+        );
+        return;
+      }
+
+      const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
+      if (!created) {
+        ctx.ui.notify(`Tool already registered: ${toolName}`, 'warning');
+        return;
+      }
+
+      ctx.ui.notify(`Registered dynamic tool: ${toolName}`, 'info');
+    }
+  });
+}

package/agent-docs/examples/extensions/event-bus.ts

@@ -1,43 +1,43 @@
-/**
- * Inter-extension event bus example.
- *
- * Shows shortcut.events for communication between extensions. One extension
- * can emit events that other extensions listen to.
- *
- * Usage: /emit [event-name] [data] - emit an event on the bus
- */
-
-import type { ExtensionAPI, ExtensionContext } from 'shortcutxl';
-
-export default function (shortcut: ExtensionAPI) {
-  // Store ctx for use in event handler
-  let currentCtx: ExtensionContext | undefined;
-
-  shortcut.on('session_start', async (_event, ctx) => {
-    currentCtx = ctx;
-  });
-
-  // Listen for events from other extensions
-  shortcut.events.on('my:notification', (data) => {
-    const { message, from } = data as { message: string; from: string };
-    currentCtx?.ui.notify(`Event from ${from}: ${message}`, 'info');
-  });
-
-  // Command to emit events (emits "my:notification" which the listener above receives)
-  shortcut.registerCommand('emit', {
-    description: 'Emit my:notification event (usage: /emit message)',
-    handler: async (args, _ctx) => {
-      const message = args.trim() || 'hello';
-      shortcut.events.emit('my:notification', { message, from: '/emit command' });
-      // Listener above will show the notification
-    }
-  });
-
-  // Example: emit on session start
-  shortcut.on('session_start', async () => {
-    shortcut.events.emit('my:notification', {
-      message: 'Session started',
-      from: 'event-bus-example'
-    });
-  });
-}
+/**
+ * Inter-extension event bus example.
+ *
+ * Shows shortcut.events for communication between extensions. One extension
+ * can emit events that other extensions listen to.
+ *
+ * Usage: /emit [event-name] [data] - emit an event on the bus
+ */
+
+import type { ExtensionAPI, ExtensionContext } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  // Store ctx for use in event handler
+  let currentCtx: ExtensionContext | undefined;
+
+  shortcut.on('session_start', async (_event, ctx) => {
+    currentCtx = ctx;
+  });
+
+  // Listen for events from other extensions
+  shortcut.events.on('my:notification', (data) => {
+    const { message, from } = data as { message: string; from: string };
+    currentCtx?.ui.notify(`Event from ${from}: ${message}`, 'info');
+  });
+
+  // Command to emit events (emits "my:notification" which the listener above receives)
+  shortcut.registerCommand('emit', {
+    description: 'Emit my:notification event (usage: /emit message)',
+    handler: async (args, _ctx) => {
+      const message = args.trim() || 'hello';
+      shortcut.events.emit('my:notification', { message, from: '/emit command' });
+      // Listener above will show the notification
+    }
+  });
+
+  // Example: emit on session start
+  shortcut.on('session_start', async () => {
+    shortcut.events.emit('my:notification', {
+      message: 'Session started',
+      from: 'event-bus-example'
+    });
+  });
+}

package/agent-docs/examples/extensions/file-trigger.ts

@@ -1,41 +1,41 @@
-/**
- * File Trigger Extension
- *
- * Watches a trigger file and injects its contents into the conversation.
- * Useful for external systems to send messages to the agent.
- *
- * Usage:
- *   echo "Run the tests" > /tmp/agent-trigger.txt
- */
-
-import * as fs from 'node:fs';
-import type { ExtensionAPI } from 'shortcutxl';
-
-export default function (shortcut: ExtensionAPI) {
-  shortcut.on('session_start', async (_event, ctx) => {
-    const triggerFile = '/tmp/agent-trigger.txt';
-
-    fs.watch(triggerFile, () => {
-      try {
-        const content = fs.readFileSync(triggerFile, 'utf-8').trim();
-        if (content) {
-          shortcut.sendMessage(
-            {
-              customType: 'file-trigger',
-              content: `External trigger: ${content}`,
-              display: true
-            },
-            { triggerTurn: true } // triggerTurn - get LLM to respond
-          );
-          fs.writeFileSync(triggerFile, ''); // Clear after reading
-        }
-      } catch {
-        // File might not exist yet
-      }
-    });
-
-    if (ctx.hasUI) {
-      ctx.ui.notify(`Watching ${triggerFile}`, 'info');
-    }
-  });
-}
+/**
+ * File Trigger Extension
+ *
+ * Watches a trigger file and injects its contents into the conversation.
+ * Useful for external systems to send messages to the agent.
+ *
+ * Usage:
+ *   echo "Run the tests" > /tmp/agent-trigger.txt
+ */
+
+import * as fs from 'node:fs';
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.on('session_start', async (_event, ctx) => {
+    const triggerFile = '/tmp/agent-trigger.txt';
+
+    fs.watch(triggerFile, () => {
+      try {
+        const content = fs.readFileSync(triggerFile, 'utf-8').trim();
+        if (content) {
+          shortcut.sendMessage(
+            {
+              customType: 'file-trigger',
+              content: `External trigger: ${content}`,
+              display: true
+            },
+            { triggerTurn: true } // triggerTurn - get LLM to respond
+          );
+          fs.writeFileSync(triggerFile, ''); // Clear after reading
+        }
+      } catch {
+        // File might not exist yet
+      }
+    });
+
+    if (ctx.hasUI) {
+      ctx.ui.notify(`Watching ${triggerFile}`, 'info');
+    }
+  });
+}

package/agent-docs/examples/extensions/git-checkpoint.ts

@@ -1,53 +1,53 @@
-/**
- * Git Checkpoint Extension
- *
- * Creates git stash checkpoints at each turn so /fork can restore code state.
- * When forking, offers to restore code to that point in history.
- */
-
-import type { ExtensionAPI } from 'shortcutxl';
-
-export default function (shortcut: ExtensionAPI) {
-  const checkpoints = new Map<string, string>();
-  let currentEntryId: string | undefined;
-
-  // Track the current entry ID when user messages are saved
-  shortcut.on('tool_result', async (_event, ctx) => {
-    const leaf = ctx.sessionManager.getLeafEntry();
-    if (leaf) currentEntryId = leaf.id;
-  });
-
-  shortcut.on('turn_start', async () => {
-    // Create a git stash entry before LLM makes changes
-    const { stdout } = await shortcut.exec('git', ['stash', 'create']);
-    const ref = stdout.trim();
-    if (ref && currentEntryId) {
-      checkpoints.set(currentEntryId, ref);
-    }
-  });
-
-  shortcut.on('session_before_fork', async (event, ctx) => {
-    const ref = checkpoints.get(event.entryId);
-    if (!ref) return;
-
-    if (!ctx.hasUI) {
-      // In non-interactive mode, don't restore automatically
-      return;
-    }
-
-    const choice = await ctx.ui.select('Restore code state?', [
-      'Yes, restore code to that point',
-      'No, keep current code'
-    ]);
-
-    if (choice?.startsWith('Yes')) {
-      await shortcut.exec('git', ['stash', 'apply', ref]);
-      ctx.ui.notify('Code restored to checkpoint', 'info');
-    }
-  });
-
-  shortcut.on('agent_end', async () => {
-    // Clear checkpoints after agent completes
-    checkpoints.clear();
-  });
-}
+/**
+ * Git Checkpoint Extension
+ *
+ * Creates git stash checkpoints at each turn so /fork can restore code state.
+ * When forking, offers to restore code to that point in history.
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  const checkpoints = new Map<string, string>();
+  let currentEntryId: string | undefined;
+
+  // Track the current entry ID when user messages are saved
+  shortcut.on('tool_result', async (_event, ctx) => {
+    const leaf = ctx.sessionManager.getLeafEntry();
+    if (leaf) currentEntryId = leaf.id;
+  });
+
+  shortcut.on('turn_start', async () => {
+    // Create a git stash entry before LLM makes changes
+    const { stdout } = await shortcut.exec('git', ['stash', 'create']);
+    const ref = stdout.trim();
+    if (ref && currentEntryId) {
+      checkpoints.set(currentEntryId, ref);
+    }
+  });
+
+  shortcut.on('session_before_fork', async (event, ctx) => {
+    const ref = checkpoints.get(event.entryId);
+    if (!ref) return;
+
+    if (!ctx.hasUI) {
+      // In non-interactive mode, don't restore automatically
+      return;
+    }
+
+    const choice = await ctx.ui.select('Restore code state?', [
+      'Yes, restore code to that point',
+      'No, keep current code'
+    ]);
+
+    if (choice?.startsWith('Yes')) {
+      await shortcut.exec('git', ['stash', 'apply', ref]);
+      ctx.ui.notify('Code restored to checkpoint', 'info');
+    }
+  });
+
+  shortcut.on('agent_end', async () => {
+    // Clear checkpoints after agent completes
+    checkpoints.clear();
+  });
+}