@boostecom/provider 0.0.1

package/docs/examples/skills-management.ts

@@ -0,0 +1,140 @@
+/**
+ * Example: Skills Configuration
+ *
+ * This example demonstrates how to configure Skills support in Claude Code.
+ * Skills allow Claude to access custom tools and capabilities defined in
+ * your user or project settings.
+ *
+ * Skills are loaded from:
+ * - User settings: ~/.claude/skills/ directory
+ * - Project settings: .claude/skills/ directory in your project
+ *
+ * Requirements for Skills to work:
+ * 1. settingSources must include the sources where skills are defined
+ * 2. The 'Skill' tool must be allowed (in allowedTools)
+ *
+ * NOTE: If you add 'Skill' to allowedTools but forget to set settingSources,
+ * you'll get a validation warning - skills won't load without settingSources!
+ */
+
+import { streamText } from 'ai';
+import { createClaudeCode, claudeCode } from '../dist/index.js';
+
+async function demonstrateSkills() {
+  console.log('🎯 Claude Code Skills Configuration Examples\n');
+
+  // ============================================
+  // Example 1: Default behavior (no skills)
+  // ============================================
+  console.log('1️⃣  Default behavior (Skills disabled)');
+  console.log('   - No settingSources configured');
+  console.log('   - Skills are not available');
+
+  const defaultModel = claudeCode('sonnet');
+  // This model cannot use skills
+
+  console.log('   Model created without skills support\n');
+
+  // ============================================
+  // Example 2: Enable Skills (recommended config)
+  // ============================================
+  console.log('2️⃣  Enable Skills (recommended)');
+  console.log('   - settingSources: ["user", "project"]');
+  console.log('   - allowedTools includes "Skill"');
+
+  const skillsModel = claudeCode('sonnet', {
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill', 'Read', 'Write', 'Bash'],
+  });
+
+  console.log('   Model created with skills support enabled\n');
+
+  // ============================================
+  // Example 3: Enable Skills at provider level
+  // ============================================
+  console.log('3️⃣  Enable Skills at provider level');
+  console.log('   - All models from this provider have Skills available');
+
+  const skillsProvider = createClaudeCode({
+    defaultSettings: {
+      settingSources: ['user', 'project'],
+      allowedTools: ['Skill', 'Read', 'Write', 'Bash'],
+    },
+  });
+
+  const modelFromProvider = skillsProvider('sonnet');
+
+  console.log('   Provider created with default skills support\n');
+
+  // ============================================
+  // Example 4: Project-only skills
+  // ============================================
+  console.log('4️⃣  Project-only skills');
+  console.log('   - Only load skills from project, not user settings');
+
+  const projectOnlyModel = claudeCode('sonnet', {
+    settingSources: ['project'],
+    allowedTools: ['Skill', 'Read'],
+  });
+
+  console.log('   Model created with project-only skills\n');
+
+  // ============================================
+  // Example 5: Common mistake (triggers warning)
+  // ============================================
+  console.log('5️⃣  Common mistake: Skill in allowedTools but no settingSources');
+  console.log('   - This will trigger a validation warning!');
+  console.log('   - Skills cannot load without settingSources');
+
+  // This configuration will emit a warning:
+  // "allowedTools includes 'Skill' but settingSources is not set"
+  const misconfiguredModel = claudeCode('sonnet', {
+    allowedTools: ['Skill', 'Read'], // Skill added, but...
+    // settingSources not set! Skills won't actually load.
+  });
+
+  console.log('   (Check console for validation warning)\n');
+
+  // ============================================
+  // Usage Example with Streaming
+  // ============================================
+  console.log('📝 Example Usage with streamText:');
+  console.log('');
+  console.log(`
+const { textStream } = streamText({
+  model: claudeCode('sonnet', {
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill', 'Read', 'Write', 'Bash'],
+  }),
+  prompt: 'Use my /custom-skill to help me with this task',
+});
+
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
+}
+`);
+
+  console.log('✅ Skills configuration examples completed!\n');
+
+  console.log('📖 Key Points:');
+  console.log('- settingSources must be set for skills to load');
+  console.log("- 'Skill' must be in allowedTools to invoke skills");
+  console.log('- Validation warns if Skill is allowed but settingSources is missing');
+  console.log('- Model-level settings override provider defaults\n');
+
+  console.log('📁 Where to define Skills:');
+  console.log('- User: ~/.claude/skills/your-skill/SKILL.md');
+  console.log('- Project: .claude/skills/your-skill/SKILL.md');
+  console.log('- See Claude Code documentation for skill definition syntax\n');
+}
+
+// Run the demonstration
+demonstrateSkills()
+  .then(() => {
+    console.log('Examples completed!');
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error('Example failed:', error);
+    process.exit(1);
+  });

package/docs/examples/stream-object.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env tsx
+
+/**
+ * Example: Streaming Object Generation with Partial Updates
+ *
+ * Demonstrates using streamObject() to receive incremental partial objects
+ * as the AI generates structured data. This enables real-time UI updates
+ * as each field becomes available.
+ */
+
+import { createClaudeCode } from '../dist/index.js';
+import { streamObject } from 'ai';
+import { z } from 'zod';
+
+const claudeCode = createClaudeCode();
+
+// Define a schema for the structured output
+const profileSchema = z.object({
+  name: z.string().describe('Name of the person'),
+  age: z.number().describe('Age in years'),
+  occupation: z.string().describe('Job title'),
+  hobbies: z.array(z.string()).describe('List of hobbies'),
+  bio: z.string().describe('A short biography (2-3 sentences)'),
+});
+
+async function main() {
+  console.log('=== Stream Object Example ===\n');
+  console.log('Generating a developer profile with real-time partial updates...\n');
+
+  const startTime = Date.now();
+  let firstPartialTime: number | null = null;
+  let partialCount = 0;
+
+  const { partialObjectStream, object } = streamObject({
+    model: claudeCode('sonnet'),
+    schema: profileSchema,
+    prompt:
+      'Generate a fictional software developer profile with creative hobbies and an interesting bio.',
+  });
+
+  console.log('--- Streaming Progress ---\n');
+
+  for await (const partial of partialObjectStream) {
+    partialCount++;
+
+    if (!firstPartialTime) {
+      firstPartialTime = Date.now();
+      console.log(`[First partial received after ${firstPartialTime - startTime}ms]\n`);
+    }
+
+    // Show field completion progress
+    const hasName = 'name' in partial && partial.name;
+    const hasAge = 'age' in partial && partial.age !== undefined;
+    const hasOccupation = 'occupation' in partial && partial.occupation;
+    const hobbiesCount =
+      'hobbies' in partial && Array.isArray(partial.hobbies) ? partial.hobbies.length : 0;
+    const hasBio = 'bio' in partial && partial.bio;
+
+    // Log select updates to show streaming progress
+    if (partialCount <= 5 || partialCount % 25 === 0) {
+      console.log(
+        `  Partial #${partialCount}: name=${hasName ? '✓' : '...'} age=${hasAge ? '✓' : '...'} occupation=${hasOccupation ? '✓' : '...'} hobbies=${hobbiesCount} bio=${hasBio ? '✓' : '...'}`
+      );
+    }
+  }
+
+  // Get the final validated object
+  const finalObject = await object;
+  const endTime = Date.now();
+
+  console.log('\n--- Final Object ---\n');
+  console.log(JSON.stringify(finalObject, null, 2));
+
+  console.log('\n--- Statistics ---');
+  console.log(`Total partial updates: ${partialCount}`);
+  console.log(`Time to first partial: ${firstPartialTime ? firstPartialTime - startTime : 0}ms`);
+  console.log(`Total time: ${endTime - startTime}ms`);
+}
+
+main().catch(console.error);

package/docs/examples/streaming.ts

@@ -0,0 +1,52 @@
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+
+async function main() {
+  try {
+    console.log('Starting streaming example...\n');
+    const startTime = Date.now();
+
+    // Request a longer response to clearly demonstrate streaming
+    const result = streamText({
+      model: claudeCode('opus'),
+      prompt: `Write a short story (about 300-400 words) about a programmer who discovers
+their code has become sentient. Include dialogue and describe the programmer's emotions
+as they realize what's happening.`,
+    });
+
+    // Stream the response with visual feedback
+    let chunkCount = 0;
+    let totalChars = 0;
+    let firstChunkTime: number | null = null;
+
+    console.log('--- Response ---\n');
+
+    for await (const chunk of result.textStream) {
+      if (firstChunkTime === null) {
+        firstChunkTime = Date.now();
+        console.log(`[First chunk received after ${firstChunkTime - startTime}ms]\n`);
+      }
+      process.stdout.write(chunk);
+      chunkCount++;
+      totalChars += chunk.length;
+    }
+
+    const endTime = Date.now();
+    console.log('\n\n--- Statistics ---');
+    console.log(`Total chunks received: ${chunkCount}`);
+    console.log(`Total characters: ${totalChars}`);
+    console.log(`Time to first chunk: ${firstChunkTime ? firstChunkTime - startTime : 0}ms`);
+    console.log(`Total time: ${endTime - startTime}ms`);
+    console.log(`Average chunk size: ${(totalChars / chunkCount).toFixed(1)} chars`);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+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/structured-output-repro.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env tsx
+
+/**
+ * Minimal Reproduction: Claude Code CLI Structured Output Silent Fallback
+ *
+ * This script demonstrates that the Claude Code CLI silently falls back to
+ * unstructured prose output when JSON schemas contain certain features,
+ * instead of returning `structured_output` or `error_max_structured_output_retries`.
+ *
+ * EXPECTED BEHAVIOR (per SDK docs):
+ * - Schemas with supported features → result.structured_output contains JSON
+ * - Schemas with unsupported features → result.subtype === 'error_max_structured_output_retries'
+ *
+ * ACTUAL BEHAVIOR:
+ * - Schemas with unsupported features → Silent fallback to prose text, no error
+ *
+ * Affected features:
+ * - `format` constraints (email, uri, date-time, etc.)
+ * - Complex regex patterns (lookaheads, lookbehinds, backreferences)
+ *
+ * Run: npx tsx examples/structured-output-repro.ts
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+interface TestCase {
+  name: string;
+  schema: Record<string, unknown>;
+  expectedToWork: boolean;
+}
+
+const testCases: TestCase[] = [
+  {
+    name: 'Baseline (no format, no pattern)',
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        email: { type: 'string' },
+      },
+      required: ['name', 'email'],
+      additionalProperties: false,
+    },
+    expectedToWork: true,
+  },
+  {
+    name: 'format: "email" only',
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+      required: ['name', 'email'],
+      additionalProperties: false,
+    },
+    expectedToWork: false, // Docs say supported, but CLI fails silently
+  },
+  {
+    name: 'format: "uri"',
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        website: { type: 'string', format: 'uri' },
+      },
+      required: ['name', 'website'],
+      additionalProperties: false,
+    },
+    expectedToWork: false,
+  },
+  {
+    name: 'Simple pattern (no lookahead)',
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        email: { type: 'string', pattern: '^[a-z]+@[a-z]+\\.[a-z]+$' },
+      },
+      required: ['name', 'email'],
+      additionalProperties: false,
+    },
+    expectedToWork: true,
+  },
+  {
+    name: 'Pattern with lookahead (Zod .email() style)',
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        email: {
+          type: 'string',
+          pattern:
+            "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+        },
+      },
+      required: ['name', 'email'],
+      additionalProperties: false,
+    },
+    expectedToWork: false,
+  },
+];
+
+async function runTest(testCase: TestCase): Promise<{
+  name: string;
+  hasStructuredOutput: boolean;
+  isValidJson: boolean;
+  subtype: string;
+  outputPreview: string;
+}> {
+  let hasStructuredOutput = false;
+  let isValidJson = false;
+  let subtype = '';
+  let outputPreview = '';
+
+  try {
+    for await (const message of query({
+      prompt: 'Generate a user profile with name and email for Sarah.',
+      options: {
+        outputFormat: {
+          type: 'json_schema',
+          schema: testCase.schema,
+        },
+        model: 'sonnet',
+        maxTurns: 3,
+      },
+    })) {
+      if (message.type === 'result') {
+        subtype = message.subtype;
+        const structuredOutput = (message as { structured_output?: unknown }).structured_output;
+        hasStructuredOutput = structuredOutput !== undefined;
+
+        if (hasStructuredOutput) {
+          outputPreview = JSON.stringify(structuredOutput).substring(0, 60);
+          isValidJson = true;
+        } else if ('result' in message && message.result) {
+          outputPreview = message.result.substring(0, 60);
+          try {
+            JSON.parse(message.result);
+            isValidJson = true;
+          } catch {
+            isValidJson = false;
+          }
+        }
+      }
+    }
+  } catch (error) {
+    outputPreview = `Error: ${(error as Error).message}`;
+  }
+
+  return { name: testCase.name, hasStructuredOutput, isValidJson, subtype, outputPreview };
+}
+
+async function main() {
+  console.log('='.repeat(80));
+  console.log('Claude Code CLI Structured Output Repro');
+  console.log('='.repeat(80));
+  console.log();
+  console.log('Testing various JSON Schema features with outputFormat...');
+  console.log();
+
+  const results = [];
+
+  for (const testCase of testCases) {
+    process.stdout.write(`Testing: ${testCase.name}... `);
+    const result = await runTest(testCase);
+    results.push({ ...result, expectedToWork: testCase.expectedToWork });
+    console.log(
+      result.hasStructuredOutput
+        ? 'structured_output'
+        : result.isValidJson
+          ? 'JSON in result'
+          : 'PROSE'
+    );
+  }
+
+  console.log();
+  console.log('='.repeat(80));
+  console.log('RESULTS');
+  console.log('='.repeat(80));
+  console.log();
+  console.log(
+    '| Test Case                              | structured_output | Valid JSON | Subtype  |'
+  );
+  console.log(
+    '|----------------------------------------|-------------------|------------|----------|'
+  );
+
+  for (const r of results) {
+    const name = r.name.padEnd(38);
+    const structured = (r.hasStructuredOutput ? 'YES' : 'NO').padEnd(17);
+    const json = (r.isValidJson ? 'YES' : 'NO').padEnd(10);
+    const st = r.subtype.padEnd(8);
+    console.log(`| ${name} | ${structured} | ${json} | ${st} |`);
+  }
+
+  console.log();
+  console.log('OUTPUT PREVIEWS:');
+  for (const r of results) {
+    console.log(`  ${r.name}: ${r.outputPreview}...`);
+  }
+
+  console.log();
+  console.log('='.repeat(80));
+  console.log('BUG SUMMARY');
+  console.log('='.repeat(80));
+  console.log();
+  console.log('EXPECTED: Unsupported schema features should return:');
+  console.log('  - subtype: "error_max_structured_output_retries"');
+  console.log('  - OR: An error indicating the schema is not supported');
+  console.log();
+  console.log('ACTUAL: Unsupported schema features cause:');
+  console.log('  - Silent fallback to unstructured prose');
+  console.log('  - subtype: "success" (misleading)');
+  console.log('  - No structured_output field');
+  console.log();
+  console.log('AFFECTED FEATURES:');
+  console.log('  - format: "email", "uri", "date-time", etc. (consistently fails)');
+  console.log('  - pattern: Complex regex may be flaky (sometimes works, sometimes fails)');
+  console.log();
+  console.log('WORKAROUND:');
+  console.log('  Use simplified schemas without format constraints for generation,');
+  console.log('  then validate with full schema client-side after receiving output.');
+  console.log();
+}
+
+main().catch(console.error);