shortcutxl 0.2.0

package/agent-docs/examples/extensions/custom-provider-qwen-cli/index.ts

@@ -0,0 +1,349 @@
+/**
+ * Qwen CLI Provider Extension
+ *
+ * Provides access to Qwen models via OAuth authentication with chat.qwen.ai.
+ * Uses device code flow with PKCE for secure browser-based authentication.
+ *
+ * Usage:
+ *   shortcut -e ./packages/coding-agent/examples/extensions/custom-provider-qwen-cli
+ *   # Then /login qwen-cli, or set QWEN_CLI_API_KEY=...
+ */
+
+import type { ExtensionAPI, OAuthCredentials, OAuthLoginCallbacks } from 'shortcutxl';
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const QWEN_DEVICE_CODE_ENDPOINT = 'https://chat.qwen.ai/api/v1/oauth2/device/code';
+const QWEN_TOKEN_ENDPOINT = 'https://chat.qwen.ai/api/v1/oauth2/token';
+const QWEN_CLIENT_ID = 'f0304373b74a44d2b584a3fb70ca9e56';
+const QWEN_SCOPE = 'openid profile email model.completion';
+const QWEN_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+const QWEN_DEFAULT_BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
+const QWEN_POLL_INTERVAL_MS = 2000;
+
+// =============================================================================
+// PKCE Helpers
+// =============================================================================
+
+async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  const verifier = btoa(String.fromCharCode(...array))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hash = await crypto.subtle.digest('SHA-256', data);
+  const challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  return { verifier, challenge };
+}
+
+// =============================================================================
+// OAuth Implementation
+// =============================================================================
+
+interface DeviceCodeResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete?: string;
+  expires_in: number;
+  interval?: number;
+}
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  token_type: string;
+  expires_in: number;
+  resource_url?: string;
+}
+
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error('Login cancelled'));
+      return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timeout);
+        reject(new Error('Login cancelled'));
+      },
+      { once: true }
+    );
+  });
+}
+
+async function startDeviceFlow(): Promise<{ deviceCode: DeviceCodeResponse; verifier: string }> {
+  const { verifier, challenge } = await generatePKCE();
+
+  const body = new URLSearchParams({
+    client_id: QWEN_CLIENT_ID,
+    scope: QWEN_SCOPE,
+    code_challenge: challenge,
+    code_challenge_method: 'S256'
+  });
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+    Accept: 'application/json'
+  };
+  const requestId = globalThis.crypto?.randomUUID?.();
+  if (requestId) headers['x-request-id'] = requestId;
+
+  const response = await fetch(QWEN_DEVICE_CODE_ENDPOINT, {
+    method: 'POST',
+    headers,
+    body: body.toString()
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Device code request failed: ${response.status} ${text}`);
+  }
+
+  const data = (await response.json()) as DeviceCodeResponse;
+
+  if (!data.device_code || !data.user_code || !data.verification_uri) {
+    throw new Error('Invalid device code response: missing required fields');
+  }
+
+  return { deviceCode: data, verifier };
+}
+
+async function pollForToken(
+  deviceCode: string,
+  verifier: string,
+  intervalSeconds: number | undefined,
+  expiresIn: number,
+  signal?: AbortSignal
+): Promise<TokenResponse> {
+  const deadline = Date.now() + expiresIn * 1000;
+  const resolvedIntervalSeconds =
+    typeof intervalSeconds === 'number' && Number.isFinite(intervalSeconds) && intervalSeconds > 0
+      ? intervalSeconds
+      : QWEN_POLL_INTERVAL_MS / 1000;
+  let intervalMs = Math.max(1000, Math.floor(resolvedIntervalSeconds * 1000));
+
+  const handleTokenError = async (error: string, description?: string): Promise<boolean> => {
+    switch (error) {
+      case 'authorization_pending':
+        await abortableSleep(intervalMs, signal);
+        return true;
+      case 'slow_down':
+        intervalMs = Math.min(intervalMs + 5000, 10000);
+        await abortableSleep(intervalMs, signal);
+        return true;
+      case 'expired_token':
+        throw new Error('Device code expired. Please restart authentication.');
+      case 'access_denied':
+        throw new Error('Authorization denied by user.');
+      default:
+        throw new Error(`Token request failed: ${error} - ${description || ''}`);
+    }
+  };
+
+  while (Date.now() < deadline) {
+    if (signal?.aborted) {
+      throw new Error('Login cancelled');
+    }
+
+    const body = new URLSearchParams({
+      grant_type: QWEN_GRANT_TYPE,
+      client_id: QWEN_CLIENT_ID,
+      device_code: deviceCode,
+      code_verifier: verifier
+    });
+
+    const response = await fetch(QWEN_TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json'
+      },
+      body: body.toString()
+    });
+
+    const responseText = await response.text();
+    let data: (TokenResponse & { error?: string; error_description?: string }) | null = null;
+    if (responseText) {
+      try {
+        data = JSON.parse(responseText) as TokenResponse & {
+          error?: string;
+          error_description?: string;
+        };
+      } catch {
+        data = null;
+      }
+    }
+
+    const error = data?.error;
+    const errorDescription = data?.error_description;
+
+    if (!response.ok) {
+      if (error && (await handleTokenError(error, errorDescription))) {
+        continue;
+      }
+      throw new Error(
+        `Token request failed: ${response.status} ${response.statusText}. Response: ${responseText}`
+      );
+    }
+
+    if (data?.access_token) {
+      return data;
+    }
+
+    if (error && (await handleTokenError(error, errorDescription))) {
+      continue;
+    }
+
+    throw new Error('Token request failed: missing access token in response');
+  }
+
+  throw new Error('Authentication timed out. Please try again.');
+}
+
+async function loginQwen(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+  const { deviceCode, verifier } = await startDeviceFlow();
+
+  // Show verification URL and user code to user
+  const authUrl = deviceCode.verification_uri_complete || deviceCode.verification_uri;
+  const instructions = deviceCode.verification_uri_complete
+    ? undefined // Code is already embedded in the URL
+    : `Enter code: ${deviceCode.user_code}`;
+  callbacks.onAuth({ url: authUrl, instructions });
+
+  // Poll for token
+  const tokenResponse = await pollForToken(
+    deviceCode.device_code,
+    verifier,
+    deviceCode.interval,
+    deviceCode.expires_in,
+    callbacks.signal
+  );
+
+  // Calculate expiry with 5-minute buffer
+  const expiresAt = Date.now() + tokenResponse.expires_in * 1000 - 5 * 60 * 1000;
+
+  return {
+    refresh: tokenResponse.refresh_token || '',
+    access: tokenResponse.access_token,
+    expires: expiresAt,
+    // Store resource_url for API base URL if provided
+    enterpriseUrl: tokenResponse.resource_url
+  };
+}
+
+async function refreshQwenToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: credentials.refresh,
+    client_id: QWEN_CLIENT_ID
+  });
+
+  const response = await fetch(QWEN_TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json'
+    },
+    body: body.toString()
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token refresh failed: ${response.status} ${text}`);
+  }
+
+  const data = (await response.json()) as TokenResponse;
+
+  if (!data.access_token) {
+    throw new Error('Token refresh failed: no access token in response');
+  }
+
+  const expiresAt = Date.now() + data.expires_in * 1000 - 5 * 60 * 1000;
+
+  return {
+    refresh: data.refresh_token || credentials.refresh,
+    access: data.access_token,
+    expires: expiresAt,
+    enterpriseUrl: data.resource_url ?? credentials.enterpriseUrl
+  };
+}
+
+function getQwenBaseUrl(resourceUrl?: string): string {
+  if (!resourceUrl) {
+    return QWEN_DEFAULT_BASE_URL;
+  }
+
+  let url = resourceUrl.startsWith('http') ? resourceUrl : `https://${resourceUrl}`;
+  if (!url.endsWith('/v1')) {
+    url = `${url}/v1`;
+  }
+  return url;
+}
+
+// =============================================================================
+// Extension Entry Point
+// =============================================================================
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerProvider('qwen-cli', {
+    baseUrl: QWEN_DEFAULT_BASE_URL,
+    apiKey: 'QWEN_CLI_API_KEY',
+    api: 'openai-completions',
+
+    models: [
+      {
+        id: 'qwen3-coder-plus',
+        name: 'Qwen3 Coder Plus',
+        reasoning: false,
+        input: ['text'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 1000000,
+        maxTokens: 65536
+      },
+      {
+        id: 'qwen3-coder-flash',
+        name: 'Qwen3 Coder Flash',
+        reasoning: false,
+        input: ['text'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 1000000,
+        maxTokens: 65536
+      },
+      {
+        id: 'vision-model',
+        name: 'Qwen3 VL Plus',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 262144,
+        maxTokens: 32768,
+        compat: { supportsDeveloperRole: false, thinkingFormat: 'qwen' }
+      }
+    ],
+
+    oauth: {
+      name: 'Qwen CLI',
+      login: loginQwen,
+      refreshToken: refreshQwenToken,
+      getApiKey: (cred) => cred.access,
+      modifyModels: (models, cred) => {
+        const baseUrl = getQwenBaseUrl(cred.enterpriseUrl as string | undefined);
+        return models.map((m) => (m.provider === 'qwen-cli' ? { ...m, baseUrl } : m));
+      }
+    }
+  });
+}

package/agent-docs/examples/extensions/custom-provider-qwen-cli/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pi-extension-custom-provider-qwen-cli",
+  "private": true,
+  "version": "1.5.4",
+  "type": "module",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/agent-docs/examples/extensions/dirty-repo-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * Dirty Repo Guard Extension
+ *
+ * Prevents session changes when there are uncommitted git changes.
+ * Useful to ensure work is committed before switching context.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from 'shortcutxl';
+
+async function checkDirtyRepo(
+  shortcut: ExtensionAPI,
+  ctx: ExtensionContext,
+  action: string
+): Promise<{ cancel: boolean } | undefined> {
+  // Check for uncommitted changes
+  const { stdout, code } = await shortcut.exec('git', ['status', '--porcelain']);
+
+  if (code !== 0) {
+    // Not a git repo, allow the action
+    return;
+  }
+
+  const hasChanges = stdout.trim().length > 0;
+  if (!hasChanges) {
+    return;
+  }
+
+  if (!ctx.hasUI) {
+    // In non-interactive mode, block by default
+    return { cancel: true };
+  }
+
+  // Count changed files
+  const changedFiles = stdout.trim().split('\n').filter(Boolean).length;
+
+  const choice = await ctx.ui.select(
+    `You have ${changedFiles} uncommitted file(s). ${action} anyway?`,
+    ['Yes, proceed anyway', 'No, let me commit first']
+  );
+
+  if (choice !== 'Yes, proceed anyway') {
+    ctx.ui.notify('Commit your changes first', 'warning');
+    return { cancel: true };
+  }
+}
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.on('session_before_switch', async (event, ctx) => {
+    const action = event.reason === 'new' ? 'new session' : 'switch session';
+    return checkDirtyRepo(shortcut, ctx, action);
+  });
+
+  shortcut.on('session_before_fork', async (_event, ctx) => {
+    return checkDirtyRepo(shortcut, ctx, 'fork');
+  });
+}

package/agent-docs/examples/extensions/doom-overlay/README.md

@@ -0,0 +1,46 @@
+# DOOM Overlay Demo
+
+Play DOOM as an overlay in Shortcut. Demonstrates that the overlay system can handle real-time game rendering at 35 FPS.
+
+## Usage
+
+```bash
+shortcut --extension ./examples/extensions/doom-overlay
+```
+
+Then run:
+```
+/doom-overlay
+```
+
+The shareware WAD file (~4MB) is auto-downloaded on first run.
+
+## Controls
+
+| Action | Keys |
+|--------|------|
+| Move | WASD or Arrow Keys |
+| Run | Shift + WASD |
+| Fire | F or Ctrl |
+| Use/Open | Space |
+| Weapons | 1-7 |
+| Map | Tab |
+| Menu | Escape |
+| Pause/Quit | Q |
+
+## How It Works
+
+DOOM runs as WebAssembly compiled from [doomgeneric](https://github.com/ozkl/doomgeneric). Each frame is rendered using half-block characters (▀) with 24-bit color, where the top pixel is the foreground color and the bottom pixel is the background color.
+
+The overlay uses:
+- `width: "90%"` - 90% of terminal width
+- `maxHeight: "80%"` - Maximum 80% of terminal height
+- `anchor: "center"` - Centered in terminal
+
+Height is calculated from width to maintain DOOM's 3.2:1 aspect ratio (accounting for half-block rendering).
+
+## Credits
+
+- [id Software](https://github.com/id-Software/DOOM) for the original DOOM
+- [doomgeneric](https://github.com/ozkl/doomgeneric) for the portable DOOM implementation
+- [pi-doom](https://github.com/badlogic/pi-doom) for the original Shortcut integration

package/agent-docs/examples/extensions/doom-overlay/doom/build.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Build DOOM for pi-doom using doomgeneric and Emscripten
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+DOOM_DIR="$PROJECT_ROOT/doom"
+BUILD_DIR="$PROJECT_ROOT/doom/build"
+
+echo "=== pi-doom Build Script ==="
+
+# Check for emcc
+if ! command -v emcc &> /dev/null; then
+    echo "Error: Emscripten (emcc) not found!"
+    echo ""
+    echo "Install via Homebrew:"
+    echo "  brew install emscripten"
+    echo ""
+    echo "Or manually:"
+    echo "  git clone https://github.com/emscripten-core/emsdk.git ~/emsdk"
+    echo "  cd ~/emsdk && ./emsdk install latest && ./emsdk activate latest"
+    echo "  source ~/emsdk/emsdk_env.sh"
+    exit 1
+fi
+
+# Clone doomgeneric if not present
+if [ ! -d "$DOOM_DIR/doomgeneric" ]; then
+    echo "Cloning doomgeneric..."
+    cd "$DOOM_DIR"
+    git clone https://github.com/ozkl/doomgeneric.git
+fi
+
+# Create build directory
+mkdir -p "$BUILD_DIR"
+
+# Copy our platform file
+cp "$DOOM_DIR/doomgeneric_pi.c" "$DOOM_DIR/doomgeneric/doomgeneric/"
+
+echo "Compiling DOOM to WebAssembly..."
+cd "$DOOM_DIR/doomgeneric/doomgeneric"
+
+# Resolution - 640x400 is doomgeneric default, good balance of speed/quality
+RESX=${DOOM_RESX:-640}
+RESY=${DOOM_RESY:-400}
+
+echo "Resolution: ${RESX}x${RESY}"
+
+# Compile with Emscripten (no sound)
+emcc -O2 \
+    -s WASM=1 \
+    -s EXPORTED_FUNCTIONS="['_doomgeneric_Create','_doomgeneric_Tick','_DG_GetFrameBuffer','_DG_GetScreenWidth','_DG_GetScreenHeight','_DG_PushKeyEvent','_malloc','_free']" \
+    -s EXPORTED_RUNTIME_METHODS="['ccall','cwrap','getValue','setValue','FS']" \
+    -s ALLOW_MEMORY_GROWTH=1 \
+    -s INITIAL_MEMORY=33554432 \
+    -s MODULARIZE=1 \
+    -s EXPORT_NAME="createDoomModule" \
+    -s ENVIRONMENT='node' \
+    -s FILESYSTEM=1 \
+    -s FORCE_FILESYSTEM=1 \
+    -s EXIT_RUNTIME=0 \
+    -s NO_EXIT_RUNTIME=1 \
+    -DDOOMGENERIC_RESX=$RESX \
+    -DDOOMGENERIC_RESY=$RESY \
+    -I. \
+    am_map.c \
+    d_event.c \
+    d_items.c \
+    d_iwad.c \
+    d_loop.c \
+    d_main.c \
+    d_mode.c \
+    d_net.c \
+    doomdef.c \
+    doomgeneric.c \
+    doomgeneric_pi.c \
+    doomstat.c \
+    dstrings.c \
+    f_finale.c \
+    f_wipe.c \
+    g_game.c \
+    hu_lib.c \
+    hu_stuff.c \
+    i_cdmus.c \
+    i_input.c \
+    i_endoom.c \
+    i_joystick.c \
+    i_scale.c \
+    i_sound.c \
+    i_system.c \
+    i_timer.c \
+    i_video.c \
+    icon.c \
+    info.c \
+    m_argv.c \
+    m_bbox.c \
+    m_cheat.c \
+    m_config.c \
+    m_controls.c \
+    m_fixed.c \
+    m_menu.c \
+    m_misc.c \
+    m_random.c \
+    memio.c \
+    p_ceilng.c \
+    p_doors.c \
+    p_enemy.c \
+    p_floor.c \
+    p_inter.c \
+    p_lights.c \
+    p_map.c \
+    p_maputl.c \
+    p_mobj.c \
+    p_plats.c \
+    p_pspr.c \
+    p_saveg.c \
+    p_setup.c \
+    p_sight.c \
+    p_spec.c \
+    p_switch.c \
+    p_telept.c \
+    p_tick.c \
+    p_user.c \
+    r_bsp.c \
+    r_data.c \
+    r_draw.c \
+    r_main.c \
+    r_plane.c \
+    r_segs.c \
+    r_sky.c \
+    r_things.c \
+    s_sound.c \
+    sha1.c \
+    sounds.c \
+    st_lib.c \
+    st_stuff.c \
+    statdump.c \
+    tables.c \
+    v_video.c \
+    w_checksum.c \
+    w_file.c \
+    w_file_stdc.c \
+    w_main.c \
+    w_wad.c \
+    wi_stuff.c \
+    z_zone.c \
+    dummy.c \
+    -o "$BUILD_DIR/doom.js"
+
+echo ""
+echo "Build complete!"
+echo "Output: $BUILD_DIR/doom.js and $BUILD_DIR/doom.wasm"

package/agent-docs/examples/extensions/doom-overlay/doom/doomgeneric_pi.c

@@ -0,0 +1,72 @@
+/**
+ * pi-doom platform implementation for doomgeneric
+ *
+ * Minimal implementation - no sound, just framebuffer and input.
+ */
+
+#include "doomgeneric.h"
+#include "doomkeys.h"
+#include <emscripten.h>
+#include <stdint.h>
+
+// Key event queue
+#define KEY_QUEUE_SIZE 256
+static struct {
+  int pressed;
+  unsigned char key;
+} key_queue[KEY_QUEUE_SIZE];
+static int key_queue_read = 0;
+static int key_queue_write = 0;
+
+// Get the framebuffer pointer for JS to read
+EMSCRIPTEN_KEEPALIVE
+uint32_t *DG_GetFrameBuffer(void) { return DG_ScreenBuffer; }
+
+// Get framebuffer dimensions
+EMSCRIPTEN_KEEPALIVE
+int DG_GetScreenWidth(void) { return DOOMGENERIC_RESX; }
+
+EMSCRIPTEN_KEEPALIVE
+int DG_GetScreenHeight(void) { return DOOMGENERIC_RESY; }
+
+// Push a key event from JavaScript
+EMSCRIPTEN_KEEPALIVE
+void DG_PushKeyEvent(int pressed, unsigned char key) {
+  int next_write = (key_queue_write + 1) % KEY_QUEUE_SIZE;
+  if (next_write != key_queue_read) {
+    key_queue[key_queue_write].pressed = pressed;
+    key_queue[key_queue_write].key = key;
+    key_queue_write = next_write;
+  }
+}
+
+void DG_Init(void) {
+  // Nothing to initialize
+}
+
+void DG_DrawFrame(void) {
+  // Frame is in DG_ScreenBuffer, JS reads via DG_GetFrameBuffer
+}
+
+void DG_SleepMs(uint32_t ms) {
+  // No-op - JS handles timing
+  (void)ms;
+}
+
+uint32_t DG_GetTicksMs(void) {
+  return (uint32_t)emscripten_get_now();
+}
+
+int DG_GetKey(int *pressed, unsigned char *key) {
+  if (key_queue_read != key_queue_write) {
+    *pressed = key_queue[key_queue_read].pressed;
+    *key = key_queue[key_queue_read].key;
+    key_queue_read = (key_queue_read + 1) % KEY_QUEUE_SIZE;
+    return 1;
+  }
+  return 0;
+}
+
+void DG_SetWindowTitle(const char *title) {
+  (void)title;
+}