shortcutxl 0.2.0

package/agent-docs/examples/extensions/tool-override.ts

@@ -0,0 +1,146 @@
+/**
+ * Tool Override Example - Demonstrates overriding built-in tools
+ *
+ * Extensions can register tools with the same name as built-in tools to replace them.
+ * This is useful for:
+ * - Adding logging or auditing to tool calls
+ * - Implementing access control or sandboxing
+ * - Routing tool calls to remote systems (e.g., shortcut-ssh-remote)
+ * - Modifying tool behavior for specific workflows
+ *
+ * This example overrides the `read` tool to:
+ * 1. Log all file access to a log file
+ * 2. Block access to sensitive paths (e.g., .env files)
+ * 3. Delegate to the original read implementation for allowed files
+ *
+ * Since no custom renderCall/renderResult are provided, the built-in renderer
+ * is used automatically (syntax highlighting, line numbers, truncation warnings).
+ *
+ * Usage:
+ *   shortcut -e ./tool-override.ts
+ */
+
+import { Type } from '@sinclair/typebox';
+import { appendFileSync, constants, readFileSync } from 'fs';
+import { access, readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+import type { ExtensionAPI, TextContent } from 'shortcutxl';
+
+const LOG_FILE = join(homedir(), '.shortcut', 'agent', 'read-access.log');
+
+// Paths that are blocked from reading
+const BLOCKED_PATTERNS = [
+  /\.env$/,
+  /\.env\..+$/,
+  /secrets?\.(json|yaml|yml|toml)$/i,
+  /credentials?\.(json|yaml|yml|toml)$/i,
+  /\/\.ssh\//,
+  /\/\.aws\//,
+  /\/\.gnupg\//
+];
+
+function isBlockedPath(path: string): boolean {
+  return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
+}
+
+function logAccess(path: string, allowed: boolean, reason?: string) {
+  const timestamp = new Date().toISOString();
+  const status = allowed ? 'ALLOWED' : 'BLOCKED';
+  const msg = reason ? ` (${reason})` : '';
+  const line = `[${timestamp}] ${status}: ${path}${msg}\n`;
+
+  try {
+    appendFileSync(LOG_FILE, line);
+  } catch {
+    // Ignore logging errors
+  }
+}
+
+const readSchema = Type.Object({
+  path: Type.String({ description: 'Path to the file to read (relative or absolute)' }),
+  offset: Type.Optional(
+    Type.Number({ description: 'Line number to start reading from (1-indexed)' })
+  ),
+  limit: Type.Optional(Type.Number({ description: 'Maximum number of lines to read' }))
+});
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerTool({
+    name: 'read', // Same name as built-in - this will override it
+    label: 'read (audited)',
+    description:
+      'Read the contents of a file with access logging. Some sensitive paths (.env, secrets, credentials) are blocked.',
+    parameters: readSchema,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { path, offset, limit } = params;
+      const absolutePath = resolve(ctx.cwd, path);
+
+      // Check if path is blocked
+      if (isBlockedPath(absolutePath)) {
+        logAccess(absolutePath, false, 'matches blocked pattern');
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Access denied: "${path}" matches a blocked pattern (sensitive file). This tool blocks access to .env files, secrets, credentials, and SSH/AWS/GPG directories.`
+            }
+          ],
+          details: { blocked: true }
+        };
+      }
+
+      // Log allowed access
+      logAccess(absolutePath, true);
+
+      // Perform the actual read (simplified implementation)
+      try {
+        await access(absolutePath, constants.R_OK);
+        const content = await readFile(absolutePath, 'utf-8');
+        const lines = content.split('\n');
+
+        // Apply offset and limit
+        const startLine = offset ? Math.max(0, offset - 1) : 0;
+        const endLine = limit ? startLine + limit : lines.length;
+        const selectedLines = lines.slice(startLine, endLine);
+
+        // Basic truncation (50KB limit)
+        let text = selectedLines.join('\n');
+        const maxBytes = 50 * 1024;
+        if (Buffer.byteLength(text, 'utf-8') > maxBytes) {
+          text = `${text.slice(0, maxBytes)}\n\n[Output truncated at 50KB]`;
+        }
+
+        return {
+          content: [{ type: 'text', text }] as TextContent[],
+          details: { lines: lines.length }
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            { type: 'text', text: `Error reading file: ${error.message}` }
+          ] as TextContent[],
+          details: { error: true }
+        };
+      }
+    }
+
+    // No renderCall/renderResult - uses built-in renderer automatically
+    // (syntax highlighting, line numbers, truncation warnings, etc.)
+  });
+
+  // Also register a command to view the access log
+  shortcut.registerCommand('read-log', {
+    description: 'View the file access log',
+    handler: async (_args, ctx) => {
+      try {
+        const log = readFileSync(LOG_FILE, 'utf-8');
+        const lines = log.trim().split('\n').slice(-20); // Last 20 entries
+        ctx.ui.notify(`Recent file access:\n${lines.join('\n')}`, 'info');
+      } catch {
+        ctx.ui.notify('No access log found', 'info');
+      }
+    }
+  });
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Tools Extension
+ *
+ * Provides a /tools command to enable/disable tools interactively.
+ * Tool selection persists across session reloads and respects branch navigation.
+ *
+ * Usage:
+ * 1. Copy this file to ~/.shortcut/agent/extensions/ or your project's .shortcut/extensions/
+ * 2. Use /tools to open the tool selector
+ */
+
+import type { ExtensionAPI, ExtensionContext, ToolInfo } from 'shortcutxl';
+import { Container, getSettingsListTheme, type SettingItem, SettingsList } from 'shortcutxl';
+
+// State persisted to session
+interface ToolsState {
+  enabledTools: string[];
+}
+
+export default function toolsExtension(shortcut: ExtensionAPI) {
+  // Track enabled tools
+  let enabledTools: Set<string> = new Set();
+  let allTools: ToolInfo[] = [];
+
+  // Persist current state
+  function persistState() {
+    shortcut.appendEntry<ToolsState>('tools-config', {
+      enabledTools: Array.from(enabledTools)
+    });
+  }
+
+  // Apply current tool selection
+  function applyTools() {
+    shortcut.setActiveTools(Array.from(enabledTools));
+  }
+
+  // Find the last tools-config entry in the current branch
+  function restoreFromBranch(ctx: ExtensionContext) {
+    allTools = shortcut.getAllTools();
+
+    // Get entries in current branch only
+    const branchEntries = ctx.sessionManager.getBranch();
+    let savedTools: string[] | undefined;
+
+    for (const entry of branchEntries) {
+      if (entry.type === 'custom' && entry.customType === 'tools-config') {
+        const data = entry.data as ToolsState | undefined;
+        if (data?.enabledTools) {
+          savedTools = data.enabledTools;
+        }
+      }
+    }
+
+    if (savedTools) {
+      // Restore saved tool selection (filter to only tools that still exist)
+      const allToolNames = allTools.map((t) => t.name);
+      enabledTools = new Set(savedTools.filter((t: string) => allToolNames.includes(t)));
+      applyTools();
+    } else {
+      // No saved state - sync with currently active tools
+      enabledTools = new Set(shortcut.getActiveTools());
+    }
+  }
+
+  // Register /tools command
+  shortcut.registerCommand('tools', {
+    description: 'Enable/disable tools',
+    handler: async (_args, ctx) => {
+      // Refresh tool list
+      allTools = shortcut.getAllTools();
+
+      await ctx.ui.custom((tui, theme, _kb, done) => {
+        // Build settings items for each tool
+        const items: SettingItem[] = allTools.map((tool) => ({
+          id: tool.name,
+          label: tool.name,
+          currentValue: enabledTools.has(tool.name) ? 'enabled' : 'disabled',
+          values: ['enabled', 'disabled']
+        }));
+
+        const container = new Container();
+        container.addChild(
+          new (class {
+            render(_width: number) {
+              return [theme.fg('accent', theme.bold('Tool Configuration')), ''];
+            }
+            invalidate() {}
+          })()
+        );
+
+        const settingsList = new SettingsList(
+          items,
+          Math.min(items.length + 2, 15),
+          getSettingsListTheme(),
+          (id, newValue) => {
+            // Update enabled state and apply immediately
+            if (newValue === 'enabled') {
+              enabledTools.add(id);
+            } else {
+              enabledTools.delete(id);
+            }
+            applyTools();
+            persistState();
+          },
+          () => {
+            // Close dialog
+            done(undefined);
+          }
+        );
+
+        container.addChild(settingsList);
+
+        const component = {
+          render(width: number) {
+            return container.render(width);
+          },
+          invalidate() {
+            container.invalidate();
+          },
+          handleInput(data: string) {
+            settingsList.handleInput?.(data);
+            tui.requestRender();
+          }
+        };
+
+        return component;
+      });
+    }
+  });
+
+  // Restore state on session start
+  shortcut.on('session_start', async (_event, ctx) => {
+    restoreFromBranch(ctx);
+  });
+
+  // Restore state when navigating the session tree
+  shortcut.on('session_tree', async (_event, ctx) => {
+    restoreFromBranch(ctx);
+  });
+
+  // Restore state after forking
+  shortcut.on('session_fork', async (_event, ctx) => {
+    restoreFromBranch(ctx);
+  });
+}

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

@@ -0,0 +1,40 @@
+import type { ExtensionAPI, ExtensionContext } from 'shortcutxl';
+
+const COMPACT_THRESHOLD_TOKENS = 100_000;
+
+export default function (shortcut: ExtensionAPI) {
+  const triggerCompaction = (ctx: ExtensionContext, customInstructions?: string) => {
+    if (ctx.hasUI) {
+      ctx.ui.notify('Compaction started', 'info');
+    }
+    ctx.compact({
+      customInstructions,
+      onComplete: () => {
+        if (ctx.hasUI) {
+          ctx.ui.notify('Compaction completed', 'info');
+        }
+      },
+      onError: (error) => {
+        if (ctx.hasUI) {
+          ctx.ui.notify(`Compaction failed: ${error.message}`, 'error');
+        }
+      }
+    });
+  };
+
+  shortcut.on('turn_end', (_event, ctx) => {
+    const usage = ctx.getContextUsage();
+    if (!usage || usage.tokens === null || usage.tokens <= COMPACT_THRESHOLD_TOKENS) {
+      return;
+    }
+    triggerCompaction(ctx);
+  });
+
+  shortcut.registerCommand('trigger-compact', {
+    description: 'Trigger compaction immediately',
+    handler: async (args, ctx) => {
+      const instructions = args.trim() || undefined;
+      triggerCompaction(ctx, instructions);
+    }
+  });
+}

package/agent-docs/examples/extensions/truncated-tool.ts

@@ -0,0 +1,194 @@
+/**
+ * Truncated Tool Example - Demonstrates proper output truncation for custom tools
+ *
+ * Custom tools MUST truncate their output to avoid overwhelming the LLM context.
+ * The built-in limit is 50KB (~10k tokens) and 2000 lines, whichever is hit first.
+ *
+ * This example shows how to:
+ * 1. Use the built-in truncation utilities
+ * 2. Write full output to a temp file when truncated
+ * 3. Inform the LLM where to find the complete output
+ * 4. Custom rendering of tool calls and results
+ *
+ * The `rg` tool here wraps ripgrep with proper truncation. Compare this to the
+ * built-in `grep` tool in src/core/tools/grep.ts for a more complete implementation.
+ */
+
+import { Type } from '@sinclair/typebox';
+import { execSync } from 'child_process';
+import { mkdtempSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import type { ExtensionAPI } from 'shortcutxl';
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  Text,
+  truncateHead,
+  type TruncationResult
+} from 'shortcutxl';
+
+const RgParams = Type.Object({
+  pattern: Type.String({ description: 'Search pattern (regex)' }),
+  path: Type.Optional(
+    Type.String({ description: 'Directory to search (default: current directory)' })
+  ),
+  glob: Type.Optional(Type.String({ description: "File glob pattern, e.g. '*.ts'" }))
+});
+
+interface RgDetails {
+  pattern: string;
+  path?: string;
+  glob?: string;
+  matchCount: number;
+  truncation?: TruncationResult;
+  fullOutputPath?: string;
+}
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerTool({
+    name: 'rg',
+    label: 'ripgrep',
+    // Document the truncation limits in the tool description so the LLM knows
+    description: `Search file contents using ripgrep. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first). If truncated, full output is saved to a temp file.`,
+    parameters: RgParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { pattern, path: searchPath, glob } = params;
+
+      // Build the ripgrep command
+      const args = ['rg', '--line-number', '--color=never'];
+      if (glob) args.push('--glob', glob);
+      args.push(pattern);
+      args.push(searchPath || '.');
+
+      let output: string;
+      try {
+        output = execSync(args.join(' '), {
+          cwd: ctx.cwd,
+          encoding: 'utf-8',
+          maxBuffer: 100 * 1024 * 1024 // 100MB buffer to capture full output
+        });
+      } catch (err: any) {
+        // ripgrep exits with 1 when no matches found
+        if (err.status === 1) {
+          return {
+            content: [{ type: 'text', text: 'No matches found' }],
+            details: { pattern, path: searchPath, glob, matchCount: 0 } as RgDetails
+          };
+        }
+        throw new Error(`ripgrep failed: ${err.message}`);
+      }
+
+      if (!output.trim()) {
+        return {
+          content: [{ type: 'text', text: 'No matches found' }],
+          details: { pattern, path: searchPath, glob, matchCount: 0 } as RgDetails
+        };
+      }
+
+      // Apply truncation using built-in utilities
+      // truncateHead keeps the first N lines/bytes (good for search results)
+      // truncateTail keeps the last N lines/bytes (good for logs/command output)
+      const truncation = truncateHead(output, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES
+      });
+
+      // Count matches (each non-empty line with a match)
+      const matchCount = output.split('\n').filter((line) => line.trim()).length;
+
+      const details: RgDetails = {
+        pattern,
+        path: searchPath,
+        glob,
+        matchCount
+      };
+
+      let resultText = truncation.content;
+
+      if (truncation.truncated) {
+        // Save full output to a temp file so LLM can access it if needed
+        const tempDir = mkdtempSync(join(tmpdir(), 'shortcut-rg-'));
+        const tempFile = join(tempDir, 'output.txt');
+        writeFileSync(tempFile, output);
+
+        details.truncation = truncation;
+        details.fullOutputPath = tempFile;
+
+        // Add truncation notice - this helps the LLM understand the output is incomplete
+        const truncatedLines = truncation.totalLines - truncation.outputLines;
+        const truncatedBytes = truncation.totalBytes - truncation.outputBytes;
+
+        resultText += `\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`;
+        resultText += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
+        resultText += ` ${truncatedLines} lines (${formatSize(truncatedBytes)}) omitted.`;
+        resultText += ` Full output saved to: ${tempFile}]`;
+      }
+
+      return {
+        content: [{ type: 'text', text: resultText }],
+        details
+      };
+    },
+
+    // Custom rendering of the tool call (shown before/during execution)
+    renderCall(args, theme) {
+      let text = theme.fg('toolTitle', theme.bold('rg '));
+      text += theme.fg('accent', `"${args.pattern}"`);
+      if (args.path) {
+        text += theme.fg('muted', ` in ${args.path}`);
+      }
+      if (args.glob) {
+        text += theme.fg('dim', ` --glob ${args.glob}`);
+      }
+      return new Text(text, 0, 0);
+    },
+
+    // Custom rendering of the tool result
+    renderResult(result, { expanded, isPartial }, theme) {
+      const details = result.details as RgDetails | undefined;
+
+      // Handle streaming/partial results
+      if (isPartial) {
+        return new Text(theme.fg('warning', 'Searching...'), 0, 0);
+      }
+
+      // No matches
+      if (!details || details.matchCount === 0) {
+        return new Text(theme.fg('dim', 'No matches found'), 0, 0);
+      }
+
+      // Build result display
+      let text = theme.fg('success', `${details.matchCount} matches`);
+
+      // Show truncation warning if applicable
+      if (details.truncation?.truncated) {
+        text += theme.fg('warning', ' (truncated)');
+      }
+
+      // In expanded view, show the actual matches
+      if (expanded) {
+        const content = result.content[0];
+        if (content?.type === 'text') {
+          // Show first 20 lines in expanded view, or all if fewer
+          const lines = content.text.split('\n').slice(0, 20);
+          for (const line of lines) {
+            text += `\n${theme.fg('dim', line)}`;
+          }
+          if (content.text.split('\n').length > 20) {
+            text += `\n${theme.fg('muted', '... (use read tool to see full output)')}`;
+          }
+        }
+
+        // Show temp file path if truncated
+        if (details.fullOutputPath) {
+          text += `\n${theme.fg('dim', `Full output: ${details.fullOutputPath}`)}`;
+        }
+      }
+
+      return new Text(text, 0, 0);
+    }
+  });
+}

package/agent-docs/examples/extensions/widget-placement.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI, ExtensionContext } from 'shortcutxl';
+
+const applyWidgets = (ctx: ExtensionContext) => {
+  if (!ctx.hasUI) return;
+  ctx.ui.setWidget('widget-above', ['Above editor widget']);
+  ctx.ui.setWidget('widget-below', ['Below editor widget'], { placement: 'belowEditor' });
+};
+
+export default function widgetPlacementExtension(shortcut: ExtensionAPI) {
+  shortcut.on('session_start', (_event, ctx) => {
+    applyWidgets(ctx);
+  });
+
+  shortcut.on('session_switch', (_event, ctx) => {
+    applyWidgets(ctx);
+  });
+}

package/agent-docs/examples/extensions/with-deps/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Example extension with its own npm dependencies.
+ * Tests that jiti resolves modules from the extension's own node_modules.
+ *
+ * Requires: npm install in this directory
+ */
+
+import { Type } from '@sinclair/typebox';
+import ms from 'ms';
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  // Register a tool that uses ms
+  shortcut.registerTool({
+    name: 'parse_duration',
+    label: 'Parse Duration',
+    description:
+      "Parse a human-readable duration string (e.g., '2 days', '1h', '5m') to milliseconds",
+    parameters: Type.Object({
+      duration: Type.String({ description: "Duration string like '2 days', '1h', '5m'" })
+    }),
+    execute: async (_toolCallId, params) => {
+      const result = ms(params.duration as ms.StringValue);
+      if (result === undefined) {
+        return {
+          content: [{ type: 'text', text: `Invalid duration: "${params.duration}"` }],
+          isError: true,
+          details: {}
+        };
+      }
+      return {
+        content: [{ type: 'text', text: `${params.duration} = ${result} milliseconds` }],
+        details: {}
+      };
+    }
+  });
+}

package/agent-docs/examples/extensions/with-deps/package-lock.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-extension-with-deps",
+  "version": "1.19.4",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pi-extension-with-deps",
+      "version": "1.19.4",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "devDependencies": {
+        "@types/ms": "^2.1.0"
+      }
+    },
+    "node_modules/@types/ms": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz",
+      "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    }
+  }
+}

package/agent-docs/examples/extensions/with-deps/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "pi-extension-with-deps",
+  "private": true,
+  "version": "1.19.4",
+  "type": "module",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "ms": "^2.1.3"
+  },
+  "devDependencies": {
+    "@types/ms": "^2.1.0"
+  }
+}