shortcutxl 0.2.12 → 0.2.13

package/agent-docs/examples/sdk/01-minimal.ts

@@ -1,22 +1,22 @@
-/**
- * Minimal SDK Usage
- *
- * Uses all defaults: discovers skills, extensions, tools, context files
- * from cwd and ~/.shortcut/agent. Model chosen from settings or first available.
- */
-
-import { createAgentSession } from 'shortcutxl';
-
-const { session } = await createAgentSession();
-
-session.subscribe((event) => {
-  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-    process.stdout.write(event.assistantMessageEvent.delta);
-  }
-});
-
-await session.prompt('What files are in the current directory?');
-session.state.messages.forEach((msg) => {
-  console.log(msg);
-});
-console.log();
+/**
+ * Minimal SDK Usage
+ *
+ * Uses all defaults: discovers skills, extensions, tools, context files
+ * from cwd and ~/.shortcut/agent. Model chosen from settings or first available.
+ */
+
+import { createAgentSession } from 'shortcutxl';
+
+const { session } = await createAgentSession();
+
+session.subscribe((event) => {
+  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt('What files are in the current directory?');
+session.state.messages.forEach((msg) => {
+  console.log(msg);
+});
+console.log();

package/agent-docs/examples/sdk/02-custom-model.ts

@@ -1,48 +1,48 @@
-/**
- * Custom Model Selection
- *
- * Shows how to select a specific model and thinking level.
- */
-
-import { AuthStorage, createAgentSession, getModel, ModelRegistry } from 'shortcutxl';
-
-// Set up auth storage and model registry
-const authStorage = AuthStorage.create();
-const modelRegistry = new ModelRegistry(authStorage);
-
-// Option 1: Find a specific built-in model by provider/id
-const opus = getModel('anthropic', 'claude-opus-4-5');
-if (opus) {
-  console.log(`Found model: ${opus.provider}/${opus.id}`);
-}
-
-// Option 2: Find model via registry (includes custom models from models.json)
-const customModel = modelRegistry.find('my-provider', 'my-model');
-if (customModel) {
-  console.log(`Found custom model: ${customModel.provider}/${customModel.id}`);
-}
-
-// Option 3: Pick from available models (have valid API keys)
-const available = await modelRegistry.getAvailable();
-console.log(
-  'Available models:',
-  available.map((m) => `${m.provider}/${m.id}`)
-);
-
-if (available.length > 0) {
-  const { session } = await createAgentSession({
-    model: available[0],
-    thinkingLevel: 'medium', // off, low, medium, high
-    authStorage,
-    modelRegistry
-  });
-
-  session.subscribe((event) => {
-    if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-      process.stdout.write(event.assistantMessageEvent.delta);
-    }
-  });
-
-  await session.prompt('Say hello in one sentence.');
-  console.log();
-}
+/**
+ * Custom Model Selection
+ *
+ * Shows how to select a specific model and thinking level.
+ */
+
+import { AuthStorage, createAgentSession, getModel, ModelRegistry } from 'shortcutxl';
+
+// Set up auth storage and model registry
+const authStorage = AuthStorage.create();
+const modelRegistry = new ModelRegistry(authStorage);
+
+// Option 1: Find a specific built-in model by provider/id
+const opus = getModel('anthropic', 'claude-opus-4-5');
+if (opus) {
+  console.log(`Found model: ${opus.provider}/${opus.id}`);
+}
+
+// Option 2: Find model via registry (includes custom models from models.json)
+const customModel = modelRegistry.find('my-provider', 'my-model');
+if (customModel) {
+  console.log(`Found custom model: ${customModel.provider}/${customModel.id}`);
+}
+
+// Option 3: Pick from available models (have valid API keys)
+const available = await modelRegistry.getAvailable();
+console.log(
+  'Available models:',
+  available.map((m) => `${m.provider}/${m.id}`)
+);
+
+if (available.length > 0) {
+  const { session } = await createAgentSession({
+    model: available[0],
+    thinkingLevel: 'medium', // off, low, medium, high
+    authStorage,
+    modelRegistry
+  });
+
+  session.subscribe((event) => {
+    if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+      process.stdout.write(event.assistantMessageEvent.delta);
+    }
+  });
+
+  await session.prompt('Say hello in one sentence.');
+  console.log();
+}

package/agent-docs/examples/sdk/03-custom-prompt.ts

@@ -1,55 +1,55 @@
-/**
- * Custom System Prompt
- *
- * Shows how to replace or modify the default system prompt.
- */
-
-import { createAgentSession, DefaultResourceLoader, SessionManager } from 'shortcutxl';
-
-// Option 1: Replace prompt entirely
-const loader1 = new DefaultResourceLoader({
-  systemPromptOverride: () => `You are a helpful assistant that speaks like a pirate.
-Always end responses with "Arrr!"`,
-  // Needed to avoid DefaultResourceLoader appending APPEND_SYSTEM.md from ~/.shortcut/agent or <cwd>/.shortcut.
-  appendSystemPromptOverride: () => []
-});
-await loader1.reload();
-
-const { session: session1 } = await createAgentSession({
-  resourceLoader: loader1,
-  sessionManager: SessionManager.inMemory()
-});
-
-session1.subscribe((event) => {
-  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-    process.stdout.write(event.assistantMessageEvent.delta);
-  }
-});
-
-console.log('=== Replace prompt ===');
-await session1.prompt('What is 2 + 2?');
-console.log('\n');
-
-// Option 2: Append instructions to the default prompt
-const loader2 = new DefaultResourceLoader({
-  appendSystemPromptOverride: (base) => [
-    ...base,
-    '## Additional Instructions\n- Always be concise\n- Use bullet points when listing things'
-  ]
-});
-await loader2.reload();
-
-const { session: session2 } = await createAgentSession({
-  resourceLoader: loader2,
-  sessionManager: SessionManager.inMemory()
-});
-
-session2.subscribe((event) => {
-  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-    process.stdout.write(event.assistantMessageEvent.delta);
-  }
-});
-
-console.log('=== Modify prompt ===');
-await session2.prompt('List 3 benefits of TypeScript.');
-console.log();
+/**
+ * Custom System Prompt
+ *
+ * Shows how to replace or modify the default system prompt.
+ */
+
+import { createAgentSession, DefaultResourceLoader, SessionManager } from 'shortcutxl';
+
+// Option 1: Replace prompt entirely
+const loader1 = new DefaultResourceLoader({
+  systemPromptOverride: () => `You are a helpful assistant that speaks like a pirate.
+Always end responses with "Arrr!"`,
+  // Needed to avoid DefaultResourceLoader appending APPEND_SYSTEM.md from ~/.shortcut/agent or <cwd>/.shortcut.
+  appendSystemPromptOverride: () => []
+});
+await loader1.reload();
+
+const { session: session1 } = await createAgentSession({
+  resourceLoader: loader1,
+  sessionManager: SessionManager.inMemory()
+});
+
+session1.subscribe((event) => {
+  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+console.log('=== Replace prompt ===');
+await session1.prompt('What is 2 + 2?');
+console.log('\n');
+
+// Option 2: Append instructions to the default prompt
+const loader2 = new DefaultResourceLoader({
+  appendSystemPromptOverride: (base) => [
+    ...base,
+    '## Additional Instructions\n- Always be concise\n- Use bullet points when listing things'
+  ]
+});
+await loader2.reload();
+
+const { session: session2 } = await createAgentSession({
+  resourceLoader: loader2,
+  sessionManager: SessionManager.inMemory()
+});
+
+session2.subscribe((event) => {
+  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+console.log('=== Modify prompt ===');
+await session2.prompt('List 3 benefits of TypeScript.');
+console.log();

package/agent-docs/examples/sdk/04-skills.ts

@@ -1,53 +1,53 @@
-/**
- * Skills Configuration
- *
- * Skills provide specialized instructions loaded into the system prompt.
- * Discover, filter, merge, or replace them.
- */
-
-import {
-  createAgentSession,
-  DefaultResourceLoader,
-  SessionManager,
-  type Skill
-} from 'shortcutxl';
-
-// Or define custom skills inline
-const customSkill: Skill = {
-  name: 'my-skill',
-  description: 'Custom project instructions',
-  filePath: '/virtual/SKILL.md',
-  baseDir: '/virtual',
-  source: 'path',
-  disableModelInvocation: false
-};
-
-const loader = new DefaultResourceLoader({
-  skillsOverride: (current) => {
-    const filteredSkills = current.skills.filter(
-      (s) => s.name.includes('browser') || s.name.includes('search')
-    );
-    return {
-      skills: [...filteredSkills, customSkill],
-      diagnostics: current.diagnostics
-    };
-  }
-});
-await loader.reload();
-
-// Discover all skills from cwd/.shortcut/skills, ~/.shortcut/agent/skills, etc.
-const { skills: allSkills, diagnostics } = loader.getSkills();
-console.log(
-  'Discovered skills:',
-  allSkills.map((s) => s.name)
-);
-if (diagnostics.length > 0) {
-  console.log('Warnings:', diagnostics);
-}
-
-await createAgentSession({
-  resourceLoader: loader,
-  sessionManager: SessionManager.inMemory()
-});
-
-console.log('Session created with filtered skills');
+/**
+ * Skills Configuration
+ *
+ * Skills provide specialized instructions loaded into the system prompt.
+ * Discover, filter, merge, or replace them.
+ */
+
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  SessionManager,
+  type Skill
+} from 'shortcutxl';
+
+// Or define custom skills inline
+const customSkill: Skill = {
+  name: 'my-skill',
+  description: 'Custom project instructions',
+  filePath: '/virtual/SKILL.md',
+  baseDir: '/virtual',
+  source: 'path',
+  disableModelInvocation: false
+};
+
+const loader = new DefaultResourceLoader({
+  skillsOverride: (current) => {
+    const filteredSkills = current.skills.filter(
+      (s) => s.name.includes('browser') || s.name.includes('search')
+    );
+    return {
+      skills: [...filteredSkills, customSkill],
+      diagnostics: current.diagnostics
+    };
+  }
+});
+await loader.reload();
+
+// Discover all skills from cwd/.shortcut/skills, ~/.shortcut/agent/skills, etc.
+const { skills: allSkills, diagnostics } = loader.getSkills();
+console.log(
+  'Discovered skills:',
+  allSkills.map((s) => s.name)
+);
+if (diagnostics.length > 0) {
+  console.log('Warnings:', diagnostics);
+}
+
+await createAgentSession({
+  resourceLoader: loader,
+  sessionManager: SessionManager.inMemory()
+});
+
+console.log('Session created with filtered skills');

package/agent-docs/examples/sdk/05-tools.ts

@@ -1,56 +1,56 @@
-/**
- * Tools Configuration
- *
- * Use built-in tool sets or individual tools.
- *
- * IMPORTANT: When using a custom `cwd`, you must use the tool factory functions
- * (createCodingTools, createReadOnlyTools, createReadTool, etc.) to ensure
- * tools resolve paths relative to your cwd, not process.cwd().
- *
- * For custom tools, see 06-extensions.ts - custom tools are now registered
- * via the extensions system using shortcut.registerTool().
- */
-
-import {
-  bashTool,
-  createAgentSession,
-  createBashTool,
-  createCodingTools,
-  createGrepTool,
-  createReadTool,
-  grepTool,
-  readOnlyTools,
-  readTool,
-  SessionManager
-} from 'shortcutxl';
-
-// Read-only mode (no edit/write) - uses process.cwd()
-await createAgentSession({
-  tools: readOnlyTools,
-  sessionManager: SessionManager.inMemory()
-});
-console.log('Read-only session created');
-
-// Custom tool selection - uses process.cwd()
-await createAgentSession({
-  tools: [readTool, bashTool, grepTool],
-  sessionManager: SessionManager.inMemory()
-});
-console.log('Custom tools session created');
-
-// With custom cwd - MUST use factory functions!
-const customCwd = '/path/to/project';
-await createAgentSession({
-  cwd: customCwd,
-  tools: createCodingTools(customCwd), // Tools resolve paths relative to customCwd
-  sessionManager: SessionManager.inMemory()
-});
-console.log('Custom cwd session created');
-
-// Or pick specific tools for custom cwd
-await createAgentSession({
-  cwd: customCwd,
-  tools: [createReadTool(customCwd), createBashTool(customCwd), createGrepTool(customCwd)],
-  sessionManager: SessionManager.inMemory()
-});
-console.log('Specific tools with custom cwd session created');
+/**
+ * Tools Configuration
+ *
+ * Use built-in tool sets or individual tools.
+ *
+ * IMPORTANT: When using a custom `cwd`, you must use the tool factory functions
+ * (createCodingTools, createReadOnlyTools, createReadTool, etc.) to ensure
+ * tools resolve paths relative to your cwd, not process.cwd().
+ *
+ * For custom tools, see 06-extensions.ts - custom tools are now registered
+ * via the extensions system using shortcut.registerTool().
+ */
+
+import {
+  bashTool,
+  createAgentSession,
+  createBashTool,
+  createCodingTools,
+  createGrepTool,
+  createReadTool,
+  grepTool,
+  readOnlyTools,
+  readTool,
+  SessionManager
+} from 'shortcutxl';
+
+// Read-only mode (no edit/write) - uses process.cwd()
+await createAgentSession({
+  tools: readOnlyTools,
+  sessionManager: SessionManager.inMemory()
+});
+console.log('Read-only session created');
+
+// Custom tool selection - uses process.cwd()
+await createAgentSession({
+  tools: [readTool, bashTool, grepTool],
+  sessionManager: SessionManager.inMemory()
+});
+console.log('Custom tools session created');
+
+// With custom cwd - MUST use factory functions!
+const customCwd = '/path/to/project';
+await createAgentSession({
+  cwd: customCwd,
+  tools: createCodingTools(customCwd), // Tools resolve paths relative to customCwd
+  sessionManager: SessionManager.inMemory()
+});
+console.log('Custom cwd session created');
+
+// Or pick specific tools for custom cwd
+await createAgentSession({
+  cwd: customCwd,
+  tools: [createReadTool(customCwd), createBashTool(customCwd), createGrepTool(customCwd)],
+  sessionManager: SessionManager.inMemory()
+});
+console.log('Specific tools with custom cwd session created');

package/agent-docs/examples/sdk/06-extensions.ts

@@ -1,88 +1,88 @@
-/**
- * Extensions Configuration
- *
- * Extensions intercept agent events and can register custom tools.
- * They provide a unified system for extensions, custom tools, commands, and more.
- *
- * By default, extension files are discovered from:
- * - ~/.shortcut/agent/extensions/
- * - <cwd>/.shortcut/extensions/
- * - Paths specified in settings.json "extensions" array
- *
- * An extension is a TypeScript file that exports a default function:
- *   export default function (shortcut: ExtensionAPI) { ... }
- */
-
-import { createAgentSession, DefaultResourceLoader, SessionManager } from 'shortcutxl';
-
-// Extensions are discovered automatically from standard locations.
-// You can also add paths via settings.json or DefaultResourceLoader options.
-
-const resourceLoader = new DefaultResourceLoader({
-  additionalExtensionPaths: ['./my-logging-extension.ts', './my-safety-extension.ts'],
-  extensionFactories: [
-    (shortcut) => {
-      shortcut.on('agent_start', () => {
-        console.log('[Inline Extension] Agent starting');
-      });
-    }
-  ]
-});
-await resourceLoader.reload();
-
-const { session } = await createAgentSession({
-  resourceLoader,
-  sessionManager: SessionManager.inMemory()
-});
-
-session.subscribe((event) => {
-  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-    process.stdout.write(event.assistantMessageEvent.delta);
-  }
-});
-
-await session.prompt('List files in the current directory.');
-console.log();
-
-// Example extension file (./my-logging-extension.ts):
-/*
-import type { ExtensionAPI } from "shortcutxl";
-
-export default function (shortcut: ExtensionAPI) {
-	shortcut.on("agent_start", async () => {
-		console.log("[Extension] Agent starting");
-	});
-
-	shortcut.on("tool_call", async (event) => {
-		console.log(\`[Extension] Tool: \${event.toolName}\`);
-		// Return { block: true, reason: "..." } to block execution
-		return undefined;
-	});
-
-	shortcut.on("agent_end", async (event) => {
-		console.log(\`[Extension] Done, \${event.messages.length} messages\`);
-	});
-
-	// Register a custom tool
-	shortcut.registerTool({
-		name: "my_tool",
-		label: "My Tool",
-		description: "Does something useful",
-		parameters: Type.Object({
-			input: Type.String(),
-		}),
-		execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => ({
-			content: [{ type: "text", text: \`Processed: \${params.input}\` }],
-			details: {},
-		}),
-	});
-
-	// Register a command
-	shortcut.registerCommand("mycommand", {
-		description: "Do something",
-		handler: async (args, ctx) => {
-			ctx.ui.notify(\`Command executed with: \${args}\`);
-		},
-	});
-}
-*/
+/**
+ * Extensions Configuration
+ *
+ * Extensions intercept agent events and can register custom tools.
+ * They provide a unified system for extensions, custom tools, commands, and more.
+ *
+ * By default, extension files are discovered from:
+ * - ~/.shortcut/agent/extensions/
+ * - <cwd>/.shortcut/extensions/
+ * - Paths specified in settings.json "extensions" array
+ *
+ * An extension is a TypeScript file that exports a default function:
+ *   export default function (shortcut: ExtensionAPI) { ... }
+ */
+
+import { createAgentSession, DefaultResourceLoader, SessionManager } from 'shortcutxl';
+
+// Extensions are discovered automatically from standard locations.
+// You can also add paths via settings.json or DefaultResourceLoader options.
+
+const resourceLoader = new DefaultResourceLoader({
+  additionalExtensionPaths: ['./my-logging-extension.ts', './my-safety-extension.ts'],
+  extensionFactories: [
+    (shortcut) => {
+      shortcut.on('agent_start', () => {
+        console.log('[Inline Extension] Agent starting');
+      });
+    }
+  ]
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  resourceLoader,
+  sessionManager: SessionManager.inMemory()
+});
+
+session.subscribe((event) => {
+  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt('List files in the current directory.');
+console.log();
+
+// Example extension file (./my-logging-extension.ts):
+/*
+import type { ExtensionAPI } from "shortcutxl";
+
+export default function (shortcut: ExtensionAPI) {
+	shortcut.on("agent_start", async () => {
+		console.log("[Extension] Agent starting");
+	});
+
+	shortcut.on("tool_call", async (event) => {
+		console.log(\`[Extension] Tool: \${event.toolName}\`);
+		// Return { block: true, reason: "..." } to block execution
+		return undefined;
+	});
+
+	shortcut.on("agent_end", async (event) => {
+		console.log(\`[Extension] Done, \${event.messages.length} messages\`);
+	});
+
+	// Register a custom tool
+	shortcut.registerTool({
+		name: "my_tool",
+		label: "My Tool",
+		description: "Does something useful",
+		parameters: Type.Object({
+			input: Type.String(),
+		}),
+		execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => ({
+			content: [{ type: "text", text: \`Processed: \${params.input}\` }],
+			details: {},
+		}),
+	});
+
+	// Register a command
+	shortcut.registerCommand("mycommand", {
+		description: "Do something",
+		handler: async (args, ctx) => {
+			ctx.ui.notify(\`Command executed with: \${args}\`);
+		},
+	});
+}
+*/