@boostecom/provider 0.0.1

package/docs/examples/limitations.ts

@@ -0,0 +1,150 @@
+import { generateText, streamText } from 'ai';
+import { generateObject } from 'ai';
+import { claudeCode } from '../dist/index.js';
+import { z } from 'zod';
+
+/**
+ * Example: Provider Limitations and Unsupported Features
+ *
+ * This example explicitly demonstrates which AI SDK features are NOT supported
+ * by the Claude Code provider due to CLI limitations. It shows what happens
+ * when you try to use these features and suggests workarounds where possible.
+ */
+
+async function main() {
+  console.log('🚧 Claude Code Provider Limitations\n');
+  console.log(
+    'This example demonstrates features that are NOT supported by the Claude Code SDK.\n'
+  );
+
+  // 1. Parameters that are silently ignored
+  console.log('1. Parameters that are silently ignored:');
+  console.log('   The following AI SDK parameters have no effect with Claude Code SDK:\n');
+
+  try {
+    const { text, usage } = await generateText({
+      model: claudeCode('opus'),
+      prompt: 'Write exactly 5 words.',
+      // These parameters are part of the AI SDK spec but are ignored by Claude Code SDK
+      temperature: 0.1, // ❌ Ignored - CLI doesn't support temperature control
+      maxOutputTokens: 10, // ❌ Ignored - CLI doesn't support output length limits
+      topP: 0.9, // ❌ Ignored - CLI doesn't support nucleus sampling
+      topK: 50, // ❌ Ignored - CLI doesn't support top-k sampling
+      presencePenalty: 0.5, // ❌ Ignored - CLI doesn't support repetition penalties
+      frequencyPenalty: 0.5, // ❌ Ignored - CLI doesn't support repetition penalties
+      stopSequences: ['END'], // ❌ Ignored - CLI doesn't support custom stop sequences
+      seed: 12345, // ❌ Ignored - CLI doesn't support deterministic output
+    });
+
+    console.log('   Result:', text);
+    console.log('   Tokens used:', usage.totalTokens);
+    console.log(
+      '\n   ⚠️  Note: Despite setting maxTokens:10, the response used',
+      usage.totalTokens,
+      'tokens'
+    );
+    console.log('   ⚠️  All the above parameters were silently ignored by the CLI\n');
+  } catch (error) {
+    console.error('   Error:', error);
+  }
+
+  // 2. Object generation - native SDK support with caveats
+  console.log('2. Object generation (supported with native SDK, with caveats):');
+
+  const PersonSchema = z.object({
+    name: z.string(),
+    age: z.number(),
+    occupation: z.string(),
+  });
+
+  try {
+    console.log('   Attempting generateObject()...');
+    const { object } = await generateObject({
+      model: claudeCode('opus'),
+      schema: PersonSchema,
+      prompt: 'Generate a person who is a software developer',
+    });
+    console.log('   ✅ Object generated:', object);
+    console.log('   Note: Uses native SDK constrained decoding (outputFormat)');
+    console.log('         Schema compliance for supported JSON Schema features');
+    console.log('         Some constraints (e.g., format: "email"/"uri", complex regex) can');
+    console.log('         cause the CLI to fall back to prose with no structured_output.');
+    console.log('         See examples/structured-output-repro.ts for details.');
+  } catch (error: any) {
+    console.log('   ❌ Error:', error.message);
+  }
+
+  // 3. Tool/Function calling - not supported
+  console.log('\n3. Tool/Function calling:');
+  console.log('   ❌ Not supported - Claude Code SDK has no function calling capability');
+  console.log('   ℹ️  While MCP servers can be configured, they cannot control output format\n');
+
+  // 4. Image inputs - not supported
+  console.log('4. Image inputs:');
+  console.log('   ❌ Not supported - Claude Code SDK cannot process images');
+  console.log('   ℹ️  The supportsImageUrls property is set to false\n');
+
+  // 5. Streaming with unsupported parameters
+  console.log('5. Streaming with ignored parameters:');
+  try {
+    const { textStream } = streamText({
+      model: claudeCode('opus'),
+      prompt: 'Count to 3',
+      temperature: 0, // ❌ Still ignored in streaming mode
+      maxOutputTokens: 5, // ❌ Still ignored in streaming mode
+    });
+
+    console.log('   Streaming: ');
+    for await (const chunk of textStream) {
+      process.stdout.write(chunk);
+    }
+    console.log('\n   ⚠️  Parameters were ignored in streaming mode too\n');
+  } catch (error) {
+    console.error('   Error:', error);
+  }
+
+  // 6. Workarounds and recommendations
+  console.log('📝 Workarounds and Recommendations:\n');
+  console.log('1. For temperature control:');
+  console.log('   - Adjust your prompts to be more specific');
+  console.log('   - Use phrases like "be creative" or "be precise"\n');
+
+  console.log('2. For output length control:');
+  console.log('   - Specify length in your prompt: "Write exactly 50 words"');
+  console.log('   - Use explicit instructions: "Keep your response brief"\n');
+
+  console.log('3. For structured output:');
+  console.log('   - ✅ Supported via native SDK constrained decoding (outputFormat)');
+  console.log('   - Use generateObject/streamObject with Zod schemas');
+  console.log('   - Prefer a simplified generation schema, then validate client-side');
+  console.log('   - See structured-output-repro.ts for known CLI limitations\n');
+
+  console.log('4. For deterministic output:');
+  console.log('   - Not possible with Claude Code SDK');
+  console.log('   - Each request will produce different results\n');
+
+  console.log('5. For function calling:');
+  console.log('   - Implement your own prompt-based routing');
+  console.log("   - Parse Claude's response to determine actions\n");
+
+  console.log('🔍 Why these limitations exist:');
+  console.log('- Claude Code SDK/CLI is mainly designed for interactive coding assistance');
+  console.log("- It lacks the API's fine-grained control parameters");
+  console.log('- The provider accurately reflects what the CLI can do\n');
+
+  console.log('✅ What DOES work well:');
+  console.log('- Basic text generation and streaming');
+  console.log('- Native structured outputs for supported schema features');
+  console.log('- Conversation context via message history');
+  console.log('- Custom timeouts and session management');
+  console.log('- Abort signals for cancellation');
+  console.log('- System messages for context setting');
+}
+
+main().catch(console.error);
+// NOTE: Migrating to Claude Agent SDK:
+// - System prompt is not applied by default
+// - Filesystem settings (CLAUDE.md, settings.json) are not loaded by default
+// To restore old behavior, set:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']

package/docs/examples/logging-custom-logger.ts

@@ -0,0 +1,99 @@
+/**
+ * Custom Logger Example
+ *
+ * Run: npx tsx examples/logging-custom-logger.ts
+ *
+ * This example demonstrates how to integrate a custom logger with Claude Code.
+ * This is useful when you want to:
+ * - Route logs to an external logging service
+ * - Format logs in a specific way
+ * - Filter or transform log messages
+ * - Integrate with existing logging infrastructure
+ *
+ * Expected output:
+ * - Custom prefixed log messages (e.g., "[CUSTOM-DEBUG]")
+ * - All log levels when verbose: true
+ * - Full control over log formatting and routing
+ */
+
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+import type { Logger } from '../dist/index.js';
+
+// Custom logger that prefixes each level and adds timestamps
+const customLogger: Logger = {
+  debug: (message: string) => {
+    const timestamp = new Date().toISOString();
+    console.log(`[CUSTOM-DEBUG] ${timestamp} - ${message}`);
+  },
+  info: (message: string) => {
+    const timestamp = new Date().toISOString();
+    console.log(`[CUSTOM-INFO] ${timestamp} - ${message}`);
+  },
+  warn: (message: string) => {
+    const timestamp = new Date().toISOString();
+    console.warn(`[CUSTOM-WARN] ${timestamp} - ${message}`);
+  },
+  error: (message: string) => {
+    const timestamp = new Date().toISOString();
+    console.error(`[CUSTOM-ERROR] ${timestamp} - ${message}`);
+  },
+};
+
+async function main() {
+  console.log('=== Custom Logger Example ===\n');
+  console.log('This example shows how to integrate your own logging system.');
+  console.log('All logs will be prefixed with [CUSTOM-*] and include timestamps.\n');
+
+  try {
+    // Use custom logger with verbose mode enabled
+    const result = streamText({
+      model: claudeCode('opus', {
+        verbose: true, // Enable verbose logging to see debug/info
+        logger: customLogger, // Use our custom logger
+      }),
+      prompt: 'Say hello in 5 words',
+    });
+
+    // Stream the response
+    console.log('\nResponse:');
+    for await (const textPart of result.textStream) {
+      process.stdout.write(textPart);
+    }
+    console.log('\n');
+
+    // Get usage info
+    const usage = await result.usage;
+    console.log('Token usage:', usage);
+
+    console.log('\n✓ Custom logger successfully integrated!');
+    console.log('  All logs above are formatted with custom prefixes and timestamps');
+    console.log('  You can route these to any logging service (Datadog, Sentry, etc.)');
+  } catch (error) {
+    console.error('Error:', error);
+    console.log('\n💡 Troubleshooting:');
+    console.log('1. Install Claude Code SDK: npm install -g @anthropic-ai/claude-code');
+    console.log('2. Authenticate: claude login');
+    console.log('3. Run check-cli.ts to verify setup');
+  }
+}
+
+main().catch(console.error);
+
+// Example: Integration with popular logging libraries
+console.log('\n📚 Integration Examples:\n');
+console.log('// Winston integration:');
+console.log('const logger: Logger = {');
+console.log('  debug: (msg) => winston.debug(msg),');
+console.log('  info: (msg) => winston.info(msg),');
+console.log('  warn: (msg) => winston.warn(msg),');
+console.log('  error: (msg) => winston.error(msg),');
+console.log('};\n');
+
+console.log('// Pino integration:');
+console.log('const logger: Logger = {');
+console.log('  debug: (msg) => pino.debug(msg),');
+console.log('  info: (msg) => pino.info(msg),');
+console.log('  warn: (msg) => pino.warn(msg),');
+console.log('  error: (msg) => pino.error(msg),');
+console.log('};\n');

package/docs/examples/logging-default.ts

@@ -0,0 +1,55 @@
+/**
+ * Default Logging Example
+ *
+ * Run: npx tsx examples/logging-default.ts
+ *
+ * This example demonstrates the default logging behavior of Claude Code.
+ * By default, only warn and error messages are logged.
+ * Debug and info messages are suppressed unless verbose mode is enabled.
+ *
+ * Expected output:
+ * - No debug or info logs
+ * - Only warn/error logs if something goes wrong
+ * - Clean output focused on the actual response
+ */
+
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+
+async function main() {
+  console.log('=== Default Logging (Non-Verbose Mode) ===\n');
+  console.log('Expected behavior:');
+  console.log('- No debug or info logs');
+  console.log('- Only warn/error logs appear if needed');
+  console.log('- Clean output showing just the response\n');
+
+  try {
+    // Default logging - only warn/error messages will appear
+    const result = streamText({
+      model: claudeCode('opus'),
+      prompt: 'Say hello in 5 words',
+    });
+
+    // Stream the response
+    console.log('Response:');
+    for await (const textPart of result.textStream) {
+      process.stdout.write(textPart);
+    }
+    console.log('\n');
+
+    // Get usage info
+    const usage = await result.usage;
+    console.log('Token usage:', usage);
+
+    console.log('\n✓ Notice: No debug or info logs appeared above');
+    console.log('  This is the default behavior - only essential output is shown');
+  } catch (error) {
+    console.error('Error:', error);
+    console.log('\n💡 Troubleshooting:');
+    console.log('1. Install Claude Code SDK: npm install -g @anthropic-ai/claude-code');
+    console.log('2. Authenticate: claude login');
+    console.log('3. Run check-cli.ts to verify setup');
+  }
+}
+
+main().catch(console.error);

package/docs/examples/logging-disabled.ts

@@ -0,0 +1,74 @@
+/**
+ * Disabled Logging Example
+ *
+ * Run: npx tsx examples/logging-disabled.ts
+ *
+ * This example demonstrates how to completely disable all logging.
+ * When logger: false is set, no logs will be emitted at all.
+ *
+ * Use this when:
+ * - You want completely silent operation
+ * - Logs might interfere with output processing
+ * - Running in production with external monitoring
+ * - You don't need any diagnostic information
+ *
+ * Expected output:
+ * - Zero log messages (no debug, info, warn, or error)
+ * - Only explicit console.log statements from your code
+ * - Completely silent provider operation
+ *
+ * ⚠️  Warning: With logging disabled, you won't see:
+ * - Warning messages about misconfigurations
+ * - Error messages from the provider
+ * - Any diagnostic information
+ */
+
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+
+async function main() {
+  console.log('=== Logging Disabled Example ===\n');
+  console.log('Expected behavior:');
+  console.log('- No logs from the provider at all');
+  console.log('- Completely silent operation');
+  console.log('- Only application output is shown\n');
+
+  try {
+    // Disable all logging
+    const result = streamText({
+      model: claudeCode('opus', {
+        logger: false, // Disable all logging
+      }),
+      prompt: 'Say hello in 5 words',
+    });
+
+    // Stream the response
+    console.log('Response:');
+    for await (const textPart of result.textStream) {
+      process.stdout.write(textPart);
+    }
+    console.log('\n');
+
+    // Get usage info
+    const usage = await result.usage;
+    console.log('Token usage:', usage);
+
+    console.log('\n✓ Notice: Zero logs from the provider appeared above');
+    console.log('  The provider operated completely silently');
+    console.log('  Only our explicit console.log statements were shown');
+
+    console.log('\n⚠️  Important:');
+    console.log("  With logging disabled, you won't see warnings or errors");
+    console.log('  from the provider. Use this mode carefully!');
+  } catch (error) {
+    // Even with logging disabled, you can still catch and handle errors
+    console.error('Error:', error);
+    console.log('\n💡 Troubleshooting:');
+    console.log('1. Install Claude Code SDK: npm install -g @anthropic-ai/claude-code');
+    console.log('2. Authenticate: claude login');
+    console.log('3. Run check-cli.ts to verify setup');
+    console.log('4. Try running without logger: false to see diagnostic logs');
+  }
+}
+
+main().catch(console.error);

package/docs/examples/logging-verbose.ts

@@ -0,0 +1,64 @@
+/**
+ * Verbose Logging Example
+ *
+ * Run: npx tsx examples/logging-verbose.ts
+ *
+ * This example demonstrates verbose logging mode.
+ * When verbose: true is set, you'll see detailed debug and info logs
+ * that help you understand what's happening under the hood.
+ *
+ * Expected output:
+ * - Debug logs showing detailed execution trace
+ * - Info logs about request/response flow
+ * - Warn/error logs if issues occur
+ * - Much more detailed output for troubleshooting
+ *
+ * Use verbose mode when:
+ * - Debugging issues
+ * - Understanding the provider's behavior
+ * - Developing and testing
+ */
+
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+
+async function main() {
+  console.log('=== Verbose Logging Mode ===\n');
+  console.log('Expected behavior:');
+  console.log('- Debug logs showing internal details');
+  console.log('- Info logs about execution flow');
+  console.log('- Full visibility into what the provider is doing\n');
+
+  try {
+    // Enable verbose logging to see debug and info messages
+    const result = streamText({
+      model: claudeCode('opus', {
+        verbose: true, // Enable verbose logging
+      }),
+      prompt: 'Say hello in 5 words',
+    });
+
+    // Stream the response
+    console.log('\nResponse:');
+    for await (const textPart of result.textStream) {
+      process.stdout.write(textPart);
+    }
+    console.log('\n');
+
+    // Get usage info
+    const usage = await result.usage;
+    console.log('Token usage:', usage);
+
+    console.log('\n✓ Notice: Debug and info logs appeared above');
+    console.log('  Verbose mode provides detailed execution information');
+    console.log('  This is helpful for development and troubleshooting');
+  } catch (error) {
+    console.error('Error:', error);
+    console.log('\n💡 Troubleshooting:');
+    console.log('1. Install Claude Code SDK: npm install -g @anthropic-ai/claude-code');
+    console.log('2. Authenticate: claude login');
+    console.log('3. Run check-cli.ts to verify setup');
+  }
+}
+
+main().catch(console.error);

package/docs/examples/long-running-tasks.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env tsx
+
+/**
+ * Example: Handling Long-Running Tasks
+ *
+ * Shows how to implement custom timeouts using AbortSignal
+ * for complex tasks that may take longer than usual.
+ */
+
+import { generateText } from 'ai';
+import { claudeCode } from '../../dist/index.js';
+// NOTE: Migrating to Claude Agent SDK:
+// - System prompt is not applied by default
+// - Filesystem settings (CLAUDE.md, settings.json) are not loaded by default
+// To restore old behavior, set:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']
+
+async function withTimeout() {
+  console.log('🕐 Example 1: Custom timeout for long task\n');
+
+  // Create an AbortController with a 5-minute timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort(new Error('Request timeout after 5 minutes'));
+  }, 300000); // 5 minutes
+
+  try {
+    const { text } = await generateText({
+      model: claudeCode('opus'),
+      prompt: 'Analyze the implications of quantum computing on cryptography...',
+      abortSignal: controller.signal,
+    });
+
+    clearTimeout(timeoutId); // Clear timeout on success
+    console.log('Response:', text);
+  } catch (error: any) {
+    clearTimeout(timeoutId);
+
+    if (error.name === 'AbortError' || error.message?.includes('timeout')) {
+      console.log('❌ Request timed out after 5 minutes');
+      console.log('Consider breaking the task into smaller parts');
+    } else {
+      console.error('Error:', error);
+    }
+  }
+}
+
+async function withUserCancellation() {
+  console.log('\n🛑 Example 2: User-cancellable request\n');
+
+  const controller = new AbortController();
+
+  // Simulate user cancellation after 2 seconds
+  setTimeout(() => {
+    console.log('User clicked cancel...');
+    controller.abort(new Error('User cancelled the request'));
+  }, 2000);
+
+  try {
+    console.log('Starting long task (will be cancelled in 2 seconds)...');
+
+    const { text } = await generateText({
+      model: claudeCode('opus'),
+      prompt: 'Write a comprehensive guide to machine learning...',
+      abortSignal: controller.signal,
+    });
+
+    console.log('Response:', text);
+  } catch (error: any) {
+    // Check for various abort/cancel error patterns
+    const isAborted =
+      error.name === 'AbortError' ||
+      error.message?.includes('cancelled') ||
+      error.message?.includes('aborted');
+
+    if (isAborted) {
+      console.log('✅ Request successfully cancelled by user');
+    } else {
+      console.error('Error:', error);
+    }
+  }
+}
+
+async function withGracefulTimeout() {
+  console.log('\n⏰ Example 3: Graceful timeout with retry option\n');
+
+  async function attemptWithTimeout(timeoutMs: number) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const { text } = await generateText({
+        model: claudeCode('opus'),
+        prompt: 'Explain the theory of relativity',
+        abortSignal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+      return { success: true, text };
+    } catch (error: any) {
+      clearTimeout(timeoutId);
+
+      if (error.name === 'AbortError') {
+        return { success: false, timeout: true };
+      }
+      throw error;
+    }
+  }
+
+  // Try with 30-second timeout first
+  console.log('Attempting with 30-second timeout...');
+  let result = await attemptWithTimeout(30000);
+
+  if (!result.success && result.timeout) {
+    console.log('⏱️ First attempt timed out, trying with longer timeout...');
+
+    // Retry with 2-minute timeout
+    result = await attemptWithTimeout(120000);
+  }
+
+  if (result.success) {
+    console.log('✅ Success!', result.text);
+  } else {
+    console.log('❌ Failed even with extended timeout');
+  }
+}
+
+// Helper function for creating timeout controllers
+function createTimeoutController(ms: number, reason = 'Request timeout'): AbortController {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort(new Error(`${reason} after ${ms}ms`));
+  }, ms);
+
+  // Add cleanup method
+  (controller as any).clearTimeout = () => clearTimeout(timeoutId);
+
+  return controller;
+}
+
+async function withHelper() {
+  console.log('\n🔧 Example 4: Using timeout helper\n');
+
+  const controller = createTimeoutController(60000, 'Complex analysis timeout');
+
+  try {
+    const { text } = await generateText({
+      model: claudeCode('opus'),
+      prompt: 'Analyze this code for security vulnerabilities...',
+      abortSignal: controller.signal,
+    });
+
+    (controller as any).clearTimeout();
+    console.log('Analysis complete:', text);
+  } catch (error: any) {
+    console.error('Analysis failed:', error.message);
+  }
+}
+
+async function main() {
+  console.log('=== Long-Running Task Examples ===\n');
+  console.log('These examples show how to handle timeouts using AbortSignal');
+  console.log('following Vercel AI SDK patterns.\n');
+
+  await withTimeout();
+  await withUserCancellation();
+  await withGracefulTimeout();
+  await withHelper();
+
+  console.log('\n📝 Key Takeaways:');
+  console.log('- Use AbortController for all cancellation needs');
+  console.log('- Set custom timeouts based on task complexity');
+  console.log('- Always clear timeouts on success');
+  console.log('- Consider retry logic for timeout scenarios');
+  console.log('- More complex tasks may need longer timeouts (5-10 minutes)');
+}
+
+main().catch(console.error);