@boostecom/provider 0.0.1

package/docs/examples/agent-teams.ts

@@ -0,0 +1,122 @@
+import { claudeCode } from '../dist/index.js';
+import { generateText } from 'ai';
+
+/**
+ * Agent Teams Example with Claude Opus 4.6
+ * 
+ * Demonstrates how to use multiple specialized subagents working together
+ * as a coordinated team to accomplish complex, multi-faceted tasks.
+ * 
+ * This example showcases:
+ * - Multiple specialized agents (research, coding, testing)
+ * - Tool restrictions per agent
+ * - Coordination between agents
+ * - Extended context window usage (1M tokens in beta)
+ */
+
+async function main() {
+  console.log('=== Agent Teams Example ===\n');
+
+  // Create a model with multiple specialized subagents
+  const model = claudeCode('opus', {
+    // Enable extended context window (1M tokens - beta feature)
+    maxThinkingTokens: 10000,
+    
+    // Configure agent team with specialized roles
+    agents: {
+      // Research Agent - Specializes in information gathering
+      researcher: {
+        description: 'Expert at finding information, searching codebases, and analyzing documentation',
+        tools: ['Read', 'Grep', 'Glob', 'WebSearch', 'Skill'],
+        disallowedTools: ['Write', 'Edit', 'Bash'],
+        prompt: `You are a research specialist. Your role is to:
+- Find and analyze relevant information
+- Search through codebases systematically
+- Provide comprehensive summaries
+- Cite your sources clearly
+
+When you find information, organize it clearly and pass it to the appropriate agent.`,
+        model: 'sonnet', // Use faster model for research
+      },
+
+      // Coding Agent - Specializes in implementation
+      developer: {
+        description: 'Expert at writing, editing, and refactoring code with best practices',
+        tools: ['Read', 'Write', 'Edit', 'Grep', 'Glob', 'Skill'],
+        disallowedTools: ['Bash(rm:*)', 'Bash(sudo:*)'],
+        prompt: `You are a senior software engineer. Your role is to:
+- Write clean, maintainable code
+- Follow best practices and design patterns
+- Implement features based on research findings
+- Create well-documented code
+
+Always write tests for your implementations and coordinate with the testing agent.`,
+        model: 'opus', // Use most capable model for coding
+      },
+
+      // Testing Agent - Specializes in quality assurance
+      tester: {
+        description: 'Expert at writing tests, running test suites, and ensuring code quality',
+        tools: ['Read', 'Write', 'Bash', 'Grep', 'Skill'],
+        disallowedTools: ['Edit'],
+        prompt: `You are a QA engineer and testing specialist. Your role is to:
+- Write comprehensive test suites
+- Run tests and analyze results
+- Identify edge cases and potential bugs
+- Ensure code quality and coverage
+
+Review implementations from the developer agent and provide feedback.`,
+        model: 'haiku', // Use fast model for testing
+      },
+    },
+
+    // Enable Skills for all agents
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash'],
+    
+    // Enable extended features
+    betas: ['code-execution-tool'],
+    
+    // Session management
+    persistSession: true,
+    maxTurns: 20,
+    
+    verbose: true,
+  });
+
+  try {
+    const prompt = `I need to build a secure user authentication system for a Node.js API. Please:
+
+1. Research best practices for password hashing and session management
+2. Implement a complete auth module with:
+   - User registration with bcrypt password hashing
+   - Login with JWT tokens
+   - Session management with refresh tokens
+   - Rate limiting for security
+3. Write comprehensive tests covering all scenarios
+
+Coordinate between the research, development, and testing agents to deliver a production-ready solution.`;
+
+    console.log('Prompt:', prompt);
+    console.log('\nGenerating with agent team...\n');
+
+    const { text, usage, finishReason } = await generateText({
+      model,
+      prompt,
+    });
+
+    console.log('\n=== Result ===');
+    console.log(text);
+    
+    console.log('\n=== Usage ===');
+    console.log('Input tokens:', usage.inputTokens);
+    console.log('Output tokens:', usage.outputTokens);
+    console.log('Finish reason:', finishReason);
+
+  } catch (error) {
+    console.error('Error:', error);
+    throw error;
+  }
+}
+
+main().catch(console.error);

package/docs/examples/basic-usage.ts

@@ -0,0 +1,73 @@
+/**
+ * Basic usage example for Claude Code AI SDK Provider
+ *
+ * This example demonstrates simple text generation with the provider
+ * and shows the metadata returned from each request.
+ */
+
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+
+async function main() {
+  try {
+    // Basic text generation - streamText returns immediately, not a promise
+    const result = streamText({
+      model: claudeCode('opus'),
+      prompt: 'Explain the concept of recursion in programming in 2-3 sentences.',
+    });
+
+    // Stream the response
+    console.log('Response:');
+    for await (const textPart of result.textStream) {
+      process.stdout.write(textPart);
+    }
+    console.log('\n');
+
+    // Get final results
+    const usage = await result.usage;
+    const providerMetadata = await result.providerMetadata;
+
+    console.log('\nToken usage:', usage);
+
+    // Display provider-specific metadata
+    const metadata = providerMetadata?.['claude-code'];
+    if (metadata) {
+      console.log('\nProvider metadata:');
+
+      // Session ID is assigned by the SDK for internal tracking
+      if (metadata.sessionId) {
+        console.log(`- Session ID: ${metadata.sessionId}`);
+      }
+
+      // Performance metrics
+      if (metadata.durationMs) {
+        console.log(`- Duration: ${metadata.durationMs}ms`);
+      }
+
+      // Cost information
+      if (typeof metadata.costUsd === 'number') {
+        console.log(`- Cost: ${metadata.costUsd.toFixed(4)}`);
+        console.log('  (Pro/Max subscribers: covered by subscription)');
+      }
+
+      // Raw usage breakdown (available in usage.raw in AI SDK v6 stable)
+      if (usage?.raw) {
+        console.log('- Raw usage:', JSON.stringify(usage.raw, null, 2));
+      }
+    }
+  } 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);
+// 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/check-cli.ts

@@ -0,0 +1,51 @@
+/**
+ * Check if the Claude Code SDK is properly installed and authenticated
+ * This example verifies the setup before running other examples
+ */
+
+import { generateText } from 'ai';
+import { createClaudeCode } from '../dist/index.js';
+
+async function checkSetup() {
+  console.log('🔍 Checking Claude Code SDK setup...\n');
+
+  const claudeCode = createClaudeCode();
+
+  try {
+    // Try a simple generation to verify everything works
+    console.log('Testing SDK connection...');
+
+    const { text, usage } = await generateText({
+      model: claudeCode('opus'),
+      prompt: 'Say "Hello from Claude" and nothing else.',
+    });
+
+    console.log('✅ Claude Code SDK is working properly!');
+    console.log('Response:', text);
+    console.log('Tokens used:', usage.totalTokens);
+    console.log('\n🎉 You can run all the examples and integration tests!');
+  } catch (error: any) {
+    console.error('❌ Failed to connect to Claude Code');
+    console.error('Error:', error.message);
+
+    if (error.message?.includes('not found') || error.message?.includes('ENOENT')) {
+      console.log('\n💡 Make sure Claude Code SDK is installed:');
+      console.log('   npm install -g @anthropic-ai/claude-code');
+    } else if (error.message?.includes('authentication') || error.message?.includes('401')) {
+      console.log('\n🔐 Authentication required. Please run:');
+      console.log('   claude login');
+    } else {
+      console.log('\n🔧 Troubleshooting tips:');
+      console.log('1. Install Claude Code SDK: npm install -g @anthropic-ai/claude-code');
+      console.log('2. Authenticate: claude login');
+      console.log('3. Verify installation: claude --version');
+    }
+
+    process.exit(1);
+  }
+}
+
+checkSetup().catch((error) => {
+  console.error('Unexpected error:', error);
+  process.exit(1);
+});

package/docs/examples/conversation-history.ts

@@ -0,0 +1,69 @@
+/**
+ * Test conversation management with proper message history
+ */
+
+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']
+import type { ModelMessage } from 'ai';
+
+async function testConversation() {
+  console.log('🧪 Testing conversation with message history...');
+
+  const model = claudeCode('opus');
+  const messages: ModelMessage[] = [];
+
+  // First turn
+  console.log(`\n1️⃣ First turn...`);
+  messages.push({
+    role: 'user' as const,
+    content: "My name is Helen and I'm a data scientist. Remember this.",
+  });
+
+  const response1 = await generateText({
+    model,
+    messages,
+  });
+  console.log('Assistant:', response1.text);
+  messages.push({ role: 'assistant' as const, content: response1.text });
+
+  // Second turn - add to conversation
+  console.log(`\n2️⃣ Second turn...`);
+  messages.push({ role: 'user' as const, content: "What's my profession?" });
+
+  const response2 = await generateText({
+    model,
+    messages,
+  });
+  console.log('Assistant:', response2.text);
+
+  // Third turn - test memory
+  console.log(`\n3️⃣ Third turn...`);
+  messages.push({ role: 'assistant' as const, content: response2.text });
+  messages.push({ role: 'user' as const, content: 'And what was my name again?' });
+
+  const response3 = await generateText({
+    model,
+    messages,
+  });
+  console.log('Assistant:', response3.text);
+
+  // Check if context was maintained through message history
+  const contextMaintained = response3.text.toLowerCase().includes('helen');
+  console.log(`\n✅ Context maintained via message history:`, contextMaintained);
+}
+
+testConversation()
+  .then(() => {
+    console.log(`\n✅ Test completed`);
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error(`\n❌ Test failed:`, error);
+    process.exit(1);
+  });

package/docs/examples/custom-config.ts

@@ -0,0 +1,90 @@
+/**
+ * Custom configuration example for Claude Code AI SDK Provider
+ *
+ * This example shows how to configure the provider and models
+ * with specific settings for your use case.
+ */
+
+import { generateText } from 'ai';
+import { createClaudeCode } 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 main() {
+  console.log('🔧 Testing custom configurations...\n');
+
+  try {
+    // Example 1: Provider with default settings for all models
+    const customProvider = createClaudeCode({
+      defaultSettings: {
+        // Skip permission prompts for all operations
+        permissionMode: 'bypassPermissions',
+        // Set working directory for file operations
+        cwd: process.cwd(),
+      },
+    });
+
+    console.log('1️⃣ Using provider with default settings:');
+    const { text: response1 } = await generateText({
+      model: customProvider('opus'), // Uses default settings
+      prompt: 'What is the capital of France? Answer in one word.',
+    });
+    console.log('Response:', response1);
+
+    // Example 2: Override settings for specific model instance
+    console.log('\n2️⃣ Model with custom settings:');
+    const { text: response2 } = await generateText({
+      model: customProvider('opus', {
+        // These settings override the provider defaults
+        permissionMode: 'default', // Ask for permissions
+        maxTurns: 5, // Limit conversation turns
+      }),
+      prompt: 'Name three popular programming languages. Just list them.',
+    });
+    console.log('Response:', response2);
+
+    // Example 3: Using tool restrictions
+    console.log('\n3️⃣ Model with tool restrictions:');
+    const safeModel = customProvider('opus', {
+      // Only allow read operations
+      allowedTools: ['Read', 'LS', 'Grep', 'Glob'],
+      // Explicitly block write operations
+      disallowedTools: ['Write', 'Edit', 'Delete', 'Bash'],
+    });
+
+    const { text: response3 } = await generateText({
+      model: safeModel,
+      prompt: 'List the files in the current directory.',
+    });
+    console.log('Response:', response3);
+
+    // Example 4: Multiple model instances from same provider
+    console.log('\n4️⃣ Using multiple model instances:');
+    const opusModel1 = customProvider('opus');
+    const opusModel2 = customProvider('opus');
+
+    // Quick comparison
+    const prompt = 'Explain quantum computing in exactly 10 words.';
+
+    const { text: response4a } = await generateText({
+      model: opusModel1,
+      prompt,
+    });
+
+    const { text: response4b } = await generateText({
+      model: opusModel2,
+      prompt,
+    });
+
+    console.log('Instance 1:', response4a);
+    console.log('Instance 2:', response4b);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+main().catch(console.error);

package/docs/examples/generate-object-constraints.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env tsx
+
+/**
+ * Constrained Object Generation Examples
+ *
+ * Demonstrates validation constraints that the Claude Code CLI can enforce
+ * via constrained decoding: number ranges, simple regex patterns, array
+ * lengths, enums, and multipleOf.
+ *
+ * NOTE: Avoid Zod methods that produce unsupported JSON Schema annotations:
+ * .email(), .url(), .uuid(), .datetime() all emit `format` constraints that
+ * cause the Claude Code CLI to silently fall back to prose. Use .describe()
+ * with format hints instead, then validate client-side if strict format
+ * compliance is needed.
+ *
+ * Regex patterns WITHOUT lookaheads/lookbehinds work fine (e.g. /^\d{4}-\d{2}-\d{2}$/).
+ * Regex patterns WITH lookaheads ((?=...), (?!...)) cause silent fallback.
+ *
+ * See JSON_FIX.md for details.
+ */
+
+import { createClaudeCode } from '../dist/index.js';
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const claudeCode = createClaudeCode();
+
+console.log('=== Claude Code: Constrained Object Generation ===\n');
+
+// ---------------------------------------------------------------------------
+// Example 1: Number ranges and integer constraints
+// ---------------------------------------------------------------------------
+async function example1_numberConstraints() {
+  console.log('1. Number Ranges and Integer Constraints\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      character: z.object({
+        name: z.string().min(3).max(20).describe('Character name'),
+        level: z.number().int().min(1).max(100),
+        experience: z.number().int().min(0).max(1000000),
+        stats: z.object({
+          health: z.number().int().min(100).max(9999),
+          mana: z.number().int().min(0).max(9999),
+          strength: z.number().int().min(1).max(99),
+          defense: z.number().int().min(1).max(99),
+          speed: z.number().int().min(1).max(99),
+          luck: z.number().int().min(1).max(10).describe('Luck stat (1-10)'),
+        }),
+        inventory: z.object({
+          gold: z.number().int().min(0).max(999999),
+          items: z.number().int().min(0).max(50).describe('Number of items (max 50)'),
+          weight: z.number().min(0).max(100).describe('Inventory weight in kg'),
+        }),
+        position: z.object({
+          x: z.number().min(-1000).max(1000),
+          y: z.number().min(-1000).max(1000),
+          z: z.number().min(0).max(500).describe('Altitude'),
+        }),
+      }),
+    }),
+    prompt: 'Generate a level 45 warrior character with balanced stats and moderate inventory.',
+  });
+
+  console.log('Generated character:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Example 2: String patterns, enums, and array constraints
+// ---------------------------------------------------------------------------
+async function example2_patternsAndArrays() {
+  console.log('2. String Patterns, Enums, and Array Constraints\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      registration: z.object({
+        // Simple regex (no lookaheads) — works with CLI constrained decoding
+        username: z
+          .string()
+          .min(3)
+          .max(20)
+          .regex(/^[a-zA-Z0-9_]+$/, 'Alphanumeric and underscore only'),
+        email: z.string().describe('Email address (e.g. user@example.com)'),
+        phone: z.string().regex(/^\+?[1-9]\d{1,14}$/, 'E.164 phone format'),
+        dateOfBirth: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'YYYY-MM-DD format'),
+        socialMedia: z.object({
+          twitter: z
+            .string()
+            .regex(/^@[a-zA-Z0-9_]{1,15}$/, 'Twitter handle format')
+            .optional(),
+          github: z
+            .string()
+            .describe('GitHub username (alphanumeric or hyphens, 1-39 characters)')
+            .optional(),
+        }),
+        preferences: z.object({
+          locale: z.string().regex(/^[a-z]{2}-[A-Z]{2}$/, 'Locale format like en-US'),
+          currency: z
+            .string()
+            .length(3)
+            .regex(/^[A-Z]{3}$/, 'ISO 4217 currency code'),
+        }),
+      }),
+    }),
+    prompt:
+      'Generate a user registration for a software developer from San Francisco with a GitHub account.',
+  });
+
+  console.log('Generated registration:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Example 3: Complex combined validations (invoice)
+// ---------------------------------------------------------------------------
+async function example3_complexCombined() {
+  console.log('3. Complex Combined Validations\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      invoice: z.object({
+        invoiceNumber: z.string().regex(/^INV-\d{4}-\d{6}$/, 'Format: INV-YYYY-XXXXXX'),
+        issueDate: z
+          .string()
+          .regex(/^\d{4}-\d{2}-\d{2}$/)
+          .describe('Issue date in YYYY-MM-DD format'),
+        dueDate: z
+          .string()
+          .regex(/^\d{4}-\d{2}-\d{2}$/)
+          .describe('Due date in YYYY-MM-DD format (after issue date)'),
+        status: z.enum(['draft', 'sent', 'paid', 'overdue', 'cancelled']),
+        client: z.object({
+          name: z.string().min(2).max(100),
+          taxId: z.string().regex(/^\d{2}-\d{7}$|^\d{3}-\d{2}-\d{4}$/, 'Tax ID format'),
+          email: z.string().describe('Client email address (e.g. billing@company.com)'),
+          address: z.object({
+            country: z
+              .string()
+              .length(2)
+              .regex(/^[A-Z]{2}$/, 'ISO country code'),
+            postalCode: z.string().min(3).max(10),
+          }),
+        }),
+        lineItems: z
+          .array(
+            z.object({
+              description: z.string().min(5).max(200),
+              quantity: z.number().positive().int().max(1000),
+              unitPrice: z.number().positive().multipleOf(0.01).max(10000),
+              taxRate: z.number().min(0).max(0.3).multipleOf(0.01),
+              discount: z.number().min(0).max(0.5).multipleOf(0.01).optional(),
+            })
+          )
+          .min(1)
+          .max(50),
+        payment: z.object({
+          terms: z.enum(['net-15', 'net-30', 'net-45', 'net-60', 'due-on-receipt']),
+          method: z.enum(['bank-transfer', 'credit-card', 'check', 'paypal', 'crypto']).optional(),
+          currency: z
+            .string()
+            .length(3)
+            .regex(/^[A-Z]{3}$/, 'ISO currency code'),
+        }),
+        totals: z.object({
+          subtotal: z.number().positive().multipleOf(0.01),
+          taxAmount: z.number().min(0).multipleOf(0.01),
+          discountAmount: z.number().min(0).multipleOf(0.01).optional(),
+          total: z.number().positive().multipleOf(0.01),
+        }),
+      }),
+    }),
+    prompt:
+      'Generate an invoice for web development services with 3 line items, sent to a US company, due in 30 days. Use a recent issue date and set the due date 30 days later.',
+  });
+
+  console.log('Generated invoice:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  try {
+    await example1_numberConstraints();
+    await example2_patternsAndArrays();
+    await example3_complexCombined();
+
+    console.log('All constraint examples completed!');
+    console.log('\nConstraint types demonstrated:');
+    console.log('- Number ranges with min/max/int/multipleOf');
+    console.log('- Simple regex patterns (no lookaheads)');
+    console.log('- String length constraints');
+    console.log('- Array length constraints (min/max)');
+    console.log('- Enums for fixed value sets');
+    console.log('- Complex combined validations');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+main().catch(console.error);