shortcutxl 0.2.0

package/agent-docs/examples/extensions/sandbox/index.ts

@@ -0,0 +1,324 @@
+/**
+ * Sandbox Extension - OS-level sandboxing for bash commands
+ *
+ * Uses @anthropic-ai/sandbox-runtime to enforce filesystem and network
+ * restrictions on bash commands at the OS level (sandbox-exec on macOS,
+ * bubblewrap on Linux).
+ *
+ * Config files (merged, project takes precedence):
+ * - ~/.shortcut/agent/sandbox.json (global)
+ * - <cwd>/.shortcut/sandbox.json (project-local)
+ *
+ * Example .shortcut/sandbox.json:
+ * ```json
+ * {
+ *   "enabled": true,
+ *   "network": {
+ *     "allowedDomains": ["github.com", "*.github.com"],
+ *     "deniedDomains": []
+ *   },
+ *   "filesystem": {
+ *     "denyRead": ["~/.ssh", "~/.aws"],
+ *     "allowWrite": [".", "/tmp"],
+ *     "denyWrite": [".env"]
+ *   }
+ * }
+ * ```
+ *
+ * Usage:
+ * - `shortcut -e ./sandbox` - sandbox enabled with default/config settings
+ * - `shortcut -e ./sandbox --no-sandbox` - disable sandboxing
+ * - `/sandbox` - show current sandbox configuration
+ *
+ * Setup:
+ * 1. Copy sandbox/ directory to ~/.shortcut/agent/extensions/
+ * 2. Run `npm install` in ~/.shortcut/agent/extensions/sandbox/
+ *
+ * Linux also requires: bubblewrap, socat, ripgrep
+ */
+
+import { SandboxManager, type SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { ExtensionAPI } from 'shortcutxl';
+import { type BashOperations, createBashTool } from 'shortcutxl';
+
+interface SandboxConfig extends SandboxRuntimeConfig {
+  enabled?: boolean;
+}
+
+const DEFAULT_CONFIG: SandboxConfig = {
+  enabled: true,
+  network: {
+    allowedDomains: [
+      'npmjs.org',
+      '*.npmjs.org',
+      'registry.npmjs.org',
+      'registry.yarnpkg.com',
+      'pypi.org',
+      '*.pypi.org',
+      'github.com',
+      '*.github.com',
+      'api.github.com',
+      'raw.githubusercontent.com'
+    ],
+    deniedDomains: []
+  },
+  filesystem: {
+    denyRead: ['~/.ssh', '~/.aws', '~/.gnupg'],
+    allowWrite: ['.', '/tmp'],
+    denyWrite: ['.env', '.env.*', '*.pem', '*.key']
+  }
+};
+
+function loadConfig(cwd: string): SandboxConfig {
+  const projectConfigPath = join(cwd, '.shortcut', 'sandbox.json');
+  const globalConfigPath = join(homedir(), '.shortcut', 'agent', 'sandbox.json');
+
+  let globalConfig: Partial<SandboxConfig> = {};
+  let projectConfig: Partial<SandboxConfig> = {};
+
+  if (existsSync(globalConfigPath)) {
+    try {
+      globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf-8'));
+    } catch (e) {
+      console.error(`Warning: Could not parse ${globalConfigPath}: ${e}`);
+    }
+  }
+
+  if (existsSync(projectConfigPath)) {
+    try {
+      projectConfig = JSON.parse(readFileSync(projectConfigPath, 'utf-8'));
+    } catch (e) {
+      console.error(`Warning: Could not parse ${projectConfigPath}: ${e}`);
+    }
+  }
+
+  return deepMerge(deepMerge(DEFAULT_CONFIG, globalConfig), projectConfig);
+}
+
+function deepMerge(base: SandboxConfig, overrides: Partial<SandboxConfig>): SandboxConfig {
+  const result: SandboxConfig = { ...base };
+
+  if (overrides.enabled !== undefined) result.enabled = overrides.enabled;
+  if (overrides.network) {
+    result.network = { ...base.network, ...overrides.network };
+  }
+  if (overrides.filesystem) {
+    result.filesystem = { ...base.filesystem, ...overrides.filesystem };
+  }
+
+  const extOverrides = overrides as {
+    ignoreViolations?: Record<string, string[]>;
+    enableWeakerNestedSandbox?: boolean;
+  };
+  const extResult = result as {
+    ignoreViolations?: Record<string, string[]>;
+    enableWeakerNestedSandbox?: boolean;
+  };
+
+  if (extOverrides.ignoreViolations) {
+    extResult.ignoreViolations = extOverrides.ignoreViolations;
+  }
+  if (extOverrides.enableWeakerNestedSandbox !== undefined) {
+    extResult.enableWeakerNestedSandbox = extOverrides.enableWeakerNestedSandbox;
+  }
+
+  return result;
+}
+
+function createSandboxedBashOps(): BashOperations {
+  return {
+    async exec(command, cwd, { onData, signal, timeout }) {
+      if (!existsSync(cwd)) {
+        throw new Error(`Working directory does not exist: ${cwd}`);
+      }
+
+      const wrappedCommand = await SandboxManager.wrapWithSandbox(command);
+
+      return new Promise((resolve, reject) => {
+        const child = spawn('bash', ['-c', wrappedCommand], {
+          cwd,
+          detached: true,
+          stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        let timedOut = false;
+        let timeoutHandle: NodeJS.Timeout | undefined;
+
+        if (timeout !== undefined && timeout > 0) {
+          timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            if (child.pid) {
+              try {
+                process.kill(-child.pid, 'SIGKILL');
+              } catch {
+                child.kill('SIGKILL');
+              }
+            }
+          }, timeout * 1000);
+        }
+
+        child.stdout?.on('data', onData);
+        child.stderr?.on('data', onData);
+
+        child.on('error', (err) => {
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+          reject(err);
+        });
+
+        const onAbort = () => {
+          if (child.pid) {
+            try {
+              process.kill(-child.pid, 'SIGKILL');
+            } catch {
+              child.kill('SIGKILL');
+            }
+          }
+        };
+
+        signal?.addEventListener('abort', onAbort, { once: true });
+
+        child.on('close', (code) => {
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+          signal?.removeEventListener('abort', onAbort);
+
+          if (signal?.aborted) {
+            reject(new Error('aborted'));
+          } else if (timedOut) {
+            reject(new Error(`timeout:${timeout}`));
+          } else {
+            resolve({ exitCode: code });
+          }
+        });
+      });
+    }
+  };
+}
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerFlag('no-sandbox', {
+    description: 'Disable OS-level sandboxing for bash commands',
+    type: 'boolean',
+    default: false
+  });
+
+  const localCwd = process.cwd();
+  const localBash = createBashTool(localCwd);
+
+  let sandboxEnabled = false;
+  let sandboxInitialized = false;
+
+  shortcut.registerTool({
+    ...localBash,
+    label: 'bash (sandboxed)',
+    async execute(id, params, signal, onUpdate, _ctx) {
+      if (!sandboxEnabled || !sandboxInitialized) {
+        return localBash.execute(id, params, signal, onUpdate);
+      }
+
+      const sandboxedBash = createBashTool(localCwd, {
+        operations: createSandboxedBashOps()
+      });
+      return sandboxedBash.execute(id, params, signal, onUpdate);
+    }
+  });
+
+  shortcut.on('user_bash', () => {
+    if (!sandboxEnabled || !sandboxInitialized) return;
+    return { operations: createSandboxedBashOps() };
+  });
+
+  shortcut.on('session_start', async (_event, ctx) => {
+    const noSandbox = shortcut.getFlag('no-sandbox') as boolean;
+
+    if (noSandbox) {
+      sandboxEnabled = false;
+      ctx.ui.notify('Sandbox disabled via --no-sandbox', 'warning');
+      return;
+    }
+
+    const config = loadConfig(ctx.cwd);
+
+    if (!config.enabled) {
+      sandboxEnabled = false;
+      ctx.ui.notify('Sandbox disabled via config', 'info');
+      return;
+    }
+
+    const platform = process.platform;
+    if (platform !== 'darwin' && platform !== 'linux') {
+      sandboxEnabled = false;
+      ctx.ui.notify(`Sandbox not supported on ${platform}`, 'warning');
+      return;
+    }
+
+    try {
+      const configExt = config as unknown as {
+        ignoreViolations?: Record<string, string[]>;
+        enableWeakerNestedSandbox?: boolean;
+      };
+
+      await SandboxManager.initialize({
+        network: config.network,
+        filesystem: config.filesystem,
+        ignoreViolations: configExt.ignoreViolations,
+        enableWeakerNestedSandbox: configExt.enableWeakerNestedSandbox
+      });
+
+      sandboxEnabled = true;
+      sandboxInitialized = true;
+
+      const networkCount = config.network?.allowedDomains?.length ?? 0;
+      const writeCount = config.filesystem?.allowWrite?.length ?? 0;
+      ctx.ui.setStatus(
+        'sandbox',
+        ctx.ui.theme.fg('accent', `🔒 Sandbox: ${networkCount} domains, ${writeCount} write paths`)
+      );
+      ctx.ui.notify('Sandbox initialized', 'info');
+    } catch (err) {
+      sandboxEnabled = false;
+      ctx.ui.notify(
+        `Sandbox initialization failed: ${err instanceof Error ? err.message : err}`,
+        'error'
+      );
+    }
+  });
+
+  shortcut.on('session_shutdown', async () => {
+    if (sandboxInitialized) {
+      try {
+        await SandboxManager.reset();
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  });
+
+  shortcut.registerCommand('sandbox', {
+    description: 'Show sandbox configuration',
+    handler: async (_args, ctx) => {
+      if (!sandboxEnabled) {
+        ctx.ui.notify('Sandbox is disabled', 'info');
+        return;
+      }
+
+      const config = loadConfig(ctx.cwd);
+      const lines = [
+        'Sandbox Configuration:',
+        '',
+        'Network:',
+        `  Allowed: ${config.network?.allowedDomains?.join(', ') || '(none)'}`,
+        `  Denied: ${config.network?.deniedDomains?.join(', ') || '(none)'}`,
+        '',
+        'Filesystem:',
+        `  Deny Read: ${config.filesystem?.denyRead?.join(', ') || '(none)'}`,
+        `  Allow Write: ${config.filesystem?.allowWrite?.join(', ') || '(none)'}`,
+        `  Deny Write: ${config.filesystem?.denyWrite?.join(', ') || '(none)'}`
+      ];
+      ctx.ui.notify(lines.join('\n'), 'info');
+    }
+  });
+}

package/agent-docs/examples/extensions/sandbox/package-lock.json

@@ -0,0 +1,92 @@
+{
+  "name": "pi-extension-sandbox",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pi-extension-sandbox",
+      "version": "1.0.0",
+      "dependencies": {
+        "@anthropic-ai/sandbox-runtime": "^0.0.26"
+      }
+    },
+    "node_modules/@anthropic-ai/sandbox-runtime": {
+      "version": "0.0.26",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/sandbox-runtime/-/sandbox-runtime-0.0.26.tgz",
+      "integrity": "sha512-DYV5LSsVMnzq0lbfaYMSpxZPUMAx4+hy343dRss+pVCLIfF62qOhxpYfZ5TmOk1GTDQm5f9wPprMNSStmnsV4w==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@pondwader/socks5-server": "^1.0.10",
+        "@types/lodash-es": "^4.17.12",
+        "commander": "^12.1.0",
+        "lodash-es": "^4.17.21",
+        "shell-quote": "^1.8.3",
+        "zod": "^3.24.1"
+      },
+      "bin": {
+        "srt": "dist/cli.js"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@pondwader/socks5-server": {
+      "version": "1.0.10",
+      "resolved": "https://registry.npmjs.org/@pondwader/socks5-server/-/socks5-server-1.0.10.tgz",
+      "integrity": "sha512-bQY06wzzR8D2+vVCUoBsr5QS2U6UgPUQRmErNwtsuI6vLcyRKkafjkr3KxbtGFf9aBBIV2mcvlsKD1UYaIV+sg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/lodash": {
+      "version": "4.17.23",
+      "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.17.23.tgz",
+      "integrity": "sha512-RDvF6wTulMPjrNdCoYRC8gNR880JNGT8uB+REUpC2Ns4pRqQJhGz90wh7rgdXDPpCczF3VGktDuFGVnz8zP7HA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/lodash-es": {
+      "version": "4.17.12",
+      "resolved": "https://registry.npmjs.org/@types/lodash-es/-/lodash-es-4.17.12.tgz",
+      "integrity": "sha512-0NgftHUcV4v34VhXm8QBSftKVXtbkBG3ViCjs6+eJ5a6y6Mi/jiFGPc1sC7QK+9BFhWrURE3EOggmWaSxL9OzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/lodash": "*"
+      }
+    },
+    "node_modules/commander": {
+      "version": "12.1.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
+      "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/lodash-es": {
+      "version": "4.17.22",
+      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.22.tgz",
+      "integrity": "sha512-XEawp1t0gxSi9x01glktRZ5HDy0HXqrM0x5pXQM98EaI0NxO6jVM7omDOxsuEo5UIASAnm2bRp1Jt/e0a2XU8Q==",
+      "license": "MIT"
+    },
+    "node_modules/shell-quote": {
+      "version": "1.8.3",
+      "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.3.tgz",
+      "integrity": "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/agent-docs/examples/extensions/sandbox/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "pi-extension-sandbox",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.26"
+  }
+}

package/agent-docs/examples/extensions/send-user-message.ts

@@ -0,0 +1,97 @@
+/**
+ * Send User Message Example
+ *
+ * Demonstrates shortcut.sendUserMessage() for sending user messages from extensions.
+ * Unlike shortcut.sendMessage() which sends custom messages, sendUserMessage() sends
+ * actual user messages that appear in the conversation as if typed by the user.
+ *
+ * Usage:
+ *   /ask What is 2+2?     - Sends a user message (always triggers a turn)
+ *   /steer Focus on X     - Sends while streaming with steer delivery
+ *   /followup And then?   - Sends while streaming with followUp delivery
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  // Simple command that sends a user message
+  shortcut.registerCommand('ask', {
+    description: 'Send a user message to the agent',
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify('Usage: /ask <message>', 'warning');
+        return;
+      }
+
+      // sendUserMessage always triggers a turn when not streaming
+      // If streaming, it will throw (no deliverAs specified)
+      if (!ctx.isIdle()) {
+        ctx.ui.notify('Agent is busy. Use /steer or /followup instead.', 'warning');
+        return;
+      }
+
+      shortcut.sendUserMessage(args);
+    }
+  });
+
+  // Command that steers the agent mid-conversation
+  shortcut.registerCommand('steer', {
+    description: 'Send a steering message (interrupts current processing)',
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify('Usage: /steer <message>', 'warning');
+        return;
+      }
+
+      if (ctx.isIdle()) {
+        // Not streaming, just send normally
+        shortcut.sendUserMessage(args);
+      } else {
+        // Streaming - use steer to interrupt
+        shortcut.sendUserMessage(args, { deliverAs: 'steer' });
+      }
+    }
+  });
+
+  // Command that queues a follow-up message
+  shortcut.registerCommand('followup', {
+    description: 'Queue a follow-up message (waits for current processing)',
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify('Usage: /followup <message>', 'warning');
+        return;
+      }
+
+      if (ctx.isIdle()) {
+        // Not streaming, just send normally
+        shortcut.sendUserMessage(args);
+      } else {
+        // Streaming - queue as follow-up
+        shortcut.sendUserMessage(args, { deliverAs: 'followUp' });
+        ctx.ui.notify('Follow-up queued', 'info');
+      }
+    }
+  });
+
+  // Example with content array (text + images would go here)
+  shortcut.registerCommand('askwith', {
+    description: 'Send a user message with structured content',
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify('Usage: /askwith <message>', 'warning');
+        return;
+      }
+
+      if (!ctx.isIdle()) {
+        ctx.ui.notify('Agent is busy', 'warning');
+        return;
+      }
+
+      // sendUserMessage accepts string or (TextContent | ImageContent)[]
+      shortcut.sendUserMessage([
+        { type: 'text', text: `User request: ${args}` },
+        { type: 'text', text: 'Please respond concisely.' }
+      ]);
+    }
+  });
+}

package/agent-docs/examples/extensions/session-name.ts

@@ -0,0 +1,27 @@
+/**
+ * Session naming example.
+ *
+ * Shows setSessionName/getSessionName to give sessions friendly names
+ * that appear in the session selector instead of the first message.
+ *
+ * Usage: /session-name [name] - set or show session name
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.registerCommand('session-name', {
+    description: 'Set or show session name (usage: /session-name [new name])',
+    handler: async (args, ctx) => {
+      const name = args.trim();
+
+      if (name) {
+        shortcut.setSessionName(name);
+        ctx.ui.notify(`Session named: ${name}`, 'info');
+      } else {
+        const current = shortcut.getSessionName();
+        ctx.ui.notify(current ? `Session: ${current}` : 'No session name set', 'info');
+      }
+    }
+  });
+}

package/agent-docs/examples/extensions/shutdown-command.ts

@@ -0,0 +1,69 @@
+/**
+ * Shutdown Command Extension
+ *
+ * Adds a /quit command that allows extensions to trigger clean shutdown.
+ * Demonstrates how extensions can use ctx.shutdown() to exit shortcut cleanly.
+ */
+
+import { Type } from '@sinclair/typebox';
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  // Register a /quit command that cleanly exits shortcut
+  shortcut.registerCommand('quit', {
+    description: 'Exit shortcut cleanly',
+    handler: async (_args, ctx) => {
+      ctx.shutdown();
+    }
+  });
+
+  // You can also create a tool that shuts down after completing work
+  shortcut.registerTool({
+    name: 'finish_and_exit',
+    label: 'Finish and Exit',
+    description: 'Complete a task and exit shortcut',
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      // Do any final work here...
+      // Request graceful shutdown (deferred until agent is idle)
+      ctx.shutdown();
+
+      // This return is sent to the LLM before shutdown occurs
+      return {
+        content: [{ type: 'text', text: 'Shutdown requested. Exiting after this response.' }],
+        details: {}
+      };
+    }
+  });
+
+  // You could also create a more complex tool with parameters
+  shortcut.registerTool({
+    name: 'deploy_and_exit',
+    label: 'Deploy and Exit',
+    description: 'Deploy the application and exit shortcut',
+    parameters: Type.Object({
+      environment: Type.String({ description: 'Target environment (e.g., production, staging)' })
+    }),
+    async execute(_toolCallId, params, _signal, onUpdate, ctx) {
+      onUpdate?.({
+        content: [{ type: 'text', text: `Deploying to ${params.environment}...` }],
+        details: {}
+      });
+
+      // Example deployment logic
+      // const result = await shortcut.exec("npm", ["run", "deploy", params.environment], { signal });
+
+      // On success, request graceful shutdown
+      onUpdate?.({
+        content: [{ type: 'text', text: 'Deployment complete, exiting...' }],
+        details: {}
+      });
+      ctx.shutdown();
+
+      return {
+        content: [{ type: 'text', text: 'Done! Shutdown requested.' }],
+        details: { environment: params.environment }
+      };
+    }
+  });
+}