@boostecom/provider 0.0.1

package/docs/examples/tool-management.ts

@@ -0,0 +1,215 @@
+/**
+ * Example: Tool Management
+ *
+ * This example demonstrates how to manage tool permissions for Claude Code.
+ * The allowedTools and disallowedTools flags work for BOTH:
+ * - Built-in Claude tools (Bash, Edit, Read, Write, etc.)
+ * - MCP tools (mcp__serverName__toolName format)
+ *
+ * These are session-only permission overrides that use the same rule syntax
+ * as settings.json permissions.
+ */
+
+import { streamText } 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 when creating model instances, e.g.:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']
+
+async function testToolManagement() {
+  console.log('🔧 Testing Claude Code Tool Management\n');
+
+  // 1. Default behavior - all tools allowed
+  console.log('1️⃣  Default (all tools allowed)');
+  const defaultClaude = createClaudeCode();
+
+  try {
+    const result1 = streamText({
+      model: defaultClaude('opus'),
+      prompt: 'What is 2 + 2? Just give me the number.',
+    });
+
+    // Collect text from stream
+    let response1 = '';
+    for await (const chunk of result1.textStream) {
+      response1 += chunk;
+    }
+    console.log('Response:', response1.trim());
+    console.log('   (All built-in and MCP tools would be allowed)');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('\n2️⃣  Built-in tools: Allow only Bash commands');
+  // 2. Allow only specific Bash commands
+  const bashOnlyClaude = createClaudeCode({
+    defaultSettings: {
+      allowedTools: ['Bash(echo:*)', 'Bash(date)', 'Bash(pwd)'],
+    },
+  });
+
+  try {
+    const result2 = streamText({
+      model: bashOnlyClaude('opus'),
+      prompt: 'Can you show me the current date? Use the date command.',
+    });
+
+    // Collect text from stream
+    let response2 = '';
+    for await (const chunk of result2.textStream) {
+      response2 += chunk;
+    }
+    console.log('Response:', response2.trim());
+    console.log('   (Only allowed specific Bash commands)');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('\n3️⃣  Built-in tools: Block dangerous operations');
+  // 3. Block file modifications but allow reading
+  const readOnlyClaude = createClaudeCode({
+    defaultSettings: {
+      disallowedTools: ['Write', 'Edit', 'Delete', 'Bash(rm:*)', 'Bash(sudo:*)'],
+    },
+  });
+
+  try {
+    const result3 = streamText({
+      model: readOnlyClaude('opus'),
+      prompt: 'What is the capital of France? Just the city name.',
+    });
+
+    // Collect text from stream
+    let response3 = '';
+    for await (const chunk of result3.textStream) {
+      response3 += chunk;
+    }
+    console.log('Response:', response3.trim());
+    console.log('   (Can read files but not write/edit/delete)');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('\n4️⃣  Mixed: Built-in tools + MCP tools');
+  // 4. Allow specific built-in tools and MCP tools
+  const mixedClaude = createClaudeCode({
+    defaultSettings: {
+      allowedTools: [
+        'Read',
+        'LS',
+        'Bash(git log:*)',
+        'Bash(git status)',
+        'mcp__filesystem__read_file',
+        'mcp__git__status',
+      ],
+    },
+  });
+
+  try {
+    const result4 = streamText({
+      model: mixedClaude('opus'),
+      prompt: 'What is the result of 5 * 8?',
+    });
+
+    // Collect text from stream
+    let response4 = '';
+    for await (const chunk of result4.textStream) {
+      response4 += chunk;
+    }
+    console.log('Response:', response4.trim());
+    console.log('   (Only allowed read operations and git status)');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('\n5️⃣  Security lockdown: No tools at all');
+  // 5. Maximum security - explicit empty allowlist blocks all tools
+  const noToolsClaude = createClaudeCode({
+    defaultSettings: {
+      allowedTools: [], // Empty array = explicit empty allowlist = NO tools allowed
+    },
+  });
+
+  try {
+    const result5 = streamText({
+      model: noToolsClaude('opus'),
+      prompt: 'What programming language is this: console.log("Hello")?',
+    });
+
+    // Collect text from stream
+    let response5 = '';
+    for await (const chunk of result5.textStream) {
+      response5 += chunk;
+    }
+    console.log('Response:', response5.trim());
+    console.log('   (No tools allowed - explicit empty allowlist blocks everything)');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('\n6️⃣  Model-specific override');
+  // 6. Model-specific settings override provider settings
+  const baseClaude = createClaudeCode({
+    defaultSettings: {
+      disallowedTools: ['Bash', 'Write'], // Provider blocks these
+    },
+  });
+
+  try {
+    const result6 = streamText({
+      model: baseClaude('opus', {
+        // Override to allow everything for this specific call
+        disallowedTools: [],
+      }),
+      prompt: 'Name a popular web framework.',
+    });
+
+    // Collect text from stream
+    let response6 = '';
+    for await (const chunk of result6.textStream) {
+      response6 += chunk;
+    }
+    console.log('Response:', response6.trim());
+    console.log('   (Model override allows all tools for this call)');
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('\n✅ Tool management examples completed!');
+
+  console.log('\n📝 Key Points:');
+  console.log('- Flags work for BOTH built-in tools AND MCP tools');
+  console.log('- Same rule syntax as settings.json permissions');
+  console.log('- Session-only overrides (higher priority than settings files)');
+  console.log('- Use specifiers for fine-grained control: Bash(git:*)');
+  console.log('- Empty allowedTools ([]) = Explicit empty allowlist = No tools allowed');
+  console.log('- Omitting flags entirely = Falls back to normal permission system');
+
+  console.log('\n🛠️  Built-in tool names:');
+  console.log('- Bash, Edit, Read, Write, Delete, LS, Grep, Glob');
+  console.log('- WebFetch, NotebookRead, NotebookEdit');
+  console.log('- Use /permissions in Claude to see all available tools');
+
+  console.log('\n🔌 MCP tool format:');
+  console.log('- mcp__<serverName> (all tools from that server)');
+  console.log('- mcp__<serverName>__<toolName> (specific tool)');
+
+  console.log('\n🔒 Security patterns:');
+  console.log('- Read-only: disallowedTools: ["Write", "Edit", "Delete"]');
+  console.log('- No shell: disallowedTools: ["Bash"]');
+  console.log('- Safe git: allowedTools: ["Bash(git log:*)", "Bash(git diff:*)"]');
+}
+
+// Run the examples
+testToolManagement()
+  .then(() => {
+    console.log('\nAll examples completed successfully!');
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error('\nExample failed:', error);
+    process.exit(1);
+  });

package/docs/examples/tool-streaming.ts

@@ -0,0 +1,132 @@
+/**
+ * Example: Tool Streaming Events
+ *
+ * Streams a conversation that triggers Claude Code's built-in tools and prints the
+ * intermediate tool events emitted by the Vercel AI SDK integration.
+ *
+ * Requirements:
+ *   - `npm run build` (so ../dist is up to date)
+ *   - `claude login` and the CLI tools available on your PATH
+ *   - Node.js ≥ 18
+ */
+
+import { streamText } from 'ai';
+import type { CanUseTool } from '@anthropic-ai/claude-agent-sdk';
+import { claudeCode } from '../dist/index.js';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const allowAllTools: CanUseTool = async (_toolName, input) => ({
+  behavior: 'allow',
+  updatedInput: input,
+});
+
+async function main() {
+  const exampleRoot = dirname(fileURLToPath(import.meta.url));
+  const workspaceRoot = resolve(exampleRoot, '..');
+  const readmePath = resolve(workspaceRoot, 'README.md');
+
+  const result = streamText({
+    model: claudeCode('opus', {
+      streamingInput: 'always',
+      canUseTool: allowAllTools,
+      permissionMode: 'bypassPermissions',
+      allowedTools: ['Bash', 'Read'],
+      cwd: workspaceRoot,
+    }),
+    prompt: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: `List the project directory and then read ${readmePath}. Summarize the findings once the tools finish.`,
+          },
+        ],
+      },
+    ],
+  });
+
+  console.log('Listening for tool and text events...\n');
+
+  const stream = result.fullStream as AsyncIterable<any>;
+
+  for await (const part of stream) {
+    switch (part.type) {
+      case 'start':
+        console.log('⚙️ generation started');
+        break;
+      case 'start-step':
+        console.log('➡️ start-step', part.request ?? {});
+        break;
+      case 'stream-start':
+        console.log('⚡ stream-start');
+        if (Array.isArray(part.warnings) && part.warnings.length > 0) {
+          console.log(
+            '  warnings:',
+            part.warnings.map((warning: unknown) => JSON.stringify(warning))
+          );
+        }
+        break;
+      case 'response-metadata':
+        console.log(`ℹ️ session ${part.id ?? 'unknown'} (model ${part.modelId ?? 'unknown'})`);
+        break;
+      case 'tool-input-start':
+        console.log(`🔧 tool-input-start → ${part.toolName} (${part.id})`);
+        break;
+      case 'tool-input-delta':
+        console.log(`   ↳ input delta: ${part.delta}`);
+        break;
+      case 'tool-input-end':
+        console.log(`   ↳ input end (${part.id})`);
+        break;
+      case 'tool-call':
+        console.log(`🚀 tool-call → ${part.toolName} (${part.toolCallId})`);
+        break;
+      case 'tool-error':
+        console.error('⚠️ tool-error:', part.toolName, part.error);
+        break;
+      case 'tool-result': {
+        console.log(`📄 tool-result ← ${part.toolName} (${part.toolCallId})`);
+        const toolResult = part.result ?? part.output;
+        if (toolResult !== undefined) {
+          console.dir(toolResult, { depth: 4 });
+        } else {
+          console.log('   (provider reported no structured result)');
+        }
+        break;
+      }
+      case 'text-start':
+        console.log('💬 text-start');
+        break;
+      case 'text-delta':
+        {
+          const chunk = part.delta ?? part.text;
+          if (typeof chunk === 'string') {
+            process.stdout.write(chunk);
+          } else {
+            console.dir(chunk, { depth: 2 });
+          }
+        }
+        break;
+      case 'text-end':
+        console.log('\n💬 text-end\n');
+        break;
+      case 'finish':
+        console.log('✅ finish', part.finishReason);
+        console.log('   usage:', part.usage ?? part.totalUsage);
+        break;
+      case 'error':
+        console.error('❌ error part:', part.error);
+        break;
+      default:
+        console.log('⋯ other part:', part);
+        break;
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error('Example failed:', error);
+  process.exitCode = 1;
+});

package/docs/examples/zod4-compatibility-test.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env tsx
+
+/**
+ * Zod 4 Compatibility Test
+ *
+ * This example demonstrates that @boostecom/provider works correctly
+ * with Zod v4.x. It tests various Zod 4 features and schema patterns.
+ *
+ * Changes in Zod 4:
+ * - Function schemas: z.function().args().returns() -> z.function({ input, output })
+ * - Better type inference
+ * - Improved error messages
+ * - New validation features
+ */
+
+import { createClaudeCode } from '../dist/index.js';
+import { generateObject, streamText } from 'ai';
+import { z } from 'zod';
+
+const claudeCode = createClaudeCode();
+
+console.log('🧪 Testing Zod 4 Compatibility with @boostecom/provider\n');
+
+// Check Zod version
+async function checkZodVersion() {
+  try {
+    const zodPkg = await import('zod/package.json', { with: { type: 'json' } });
+    console.log(`📦 Zod version: ${zodPkg.default.version}\n`);
+  } catch {
+    console.log('📦 Zod version: 4.x (unable to read package.json)\n');
+  }
+}
+
+// Test 1: Basic Zod 4 schemas
+async function test1_basicSchemas() {
+  console.log('1️⃣  Basic Zod 4 Schemas\n');
+
+  const schema = z.object({
+    // Primitives
+    name: z.string(),
+    age: z.number(),
+    isActive: z.boolean(),
+    // Optional
+    nickname: z.string().optional(),
+    // Arrays
+    tags: z.array(z.string()),
+    // Enums
+    role: z.enum(['admin', 'user', 'guest']),
+    // Dates
+    createdAt: z.string().datetime(),
+  });
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema,
+    prompt: 'Generate a user profile for a software developer',
+  });
+
+  console.log('Generated object:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log('✅ Basic schemas work!\n');
+}
+
+// Test 2: Zod 4 function schemas (NEW API)
+async function test2_functionSchemas() {
+  console.log('2️⃣  Zod 4 Function Schemas (New API)\n');
+
+  // In Zod 4, function schemas use the new API:
+  // z.function({ input, output }) instead of z.function().args().returns()
+  // Using Zod 4 function schema API
+  const callbackSchema = z.function({
+    input: z.tuple([z.string()]),
+    output: z.void(),
+  });
+
+  console.log('Function schema created with new Zod 4 API:');
+  console.log('z.function({ input: z.tuple([z.string()]), output: z.void() })');
+
+  // Test the schema
+  const testFn = (msg: string) => console.log(msg);
+  const result = callbackSchema.safeParse(testFn);
+
+  if (result.success) {
+    console.log('✅ Function schema validation passed!\n');
+  } else {
+    console.log('❌ Function schema validation failed\n');
+  }
+}
+
+// Test 3: Complex nested objects
+async function test3_nestedObjects() {
+  console.log('3️⃣  Complex Nested Objects\n');
+
+  const schema = z.object({
+    user: z.object({
+      id: z.string(),
+      profile: z.object({
+        firstName: z.string(),
+        lastName: z.string(),
+        contact: z.object({
+          email: z.string().email(),
+          phone: z.string().optional(),
+        }),
+      }),
+    }),
+    settings: z.object({
+      theme: z.enum(['light', 'dark', 'auto']),
+      notifications: z.object({
+        email: z.boolean(),
+        push: z.boolean(),
+        sms: z.boolean(),
+      }),
+    }),
+  });
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema,
+    prompt: 'Generate a complete user profile with settings',
+  });
+
+  console.log('Generated nested object:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log('✅ Nested objects work!\n');
+}
+
+// Test 4: Arrays and unions
+async function test4_arraysAndUnions() {
+  console.log('4️⃣  Arrays and Unions\n');
+
+  const schema = z.object({
+    tasks: z.array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        status: z.union([z.literal('todo'), z.literal('in-progress'), z.literal('done')]),
+        priority: z.number().min(1).max(5),
+        assignee: z
+          .object({
+            name: z.string(),
+            email: z.string().email(),
+          })
+          .optional(),
+      })
+    ),
+  });
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema,
+    prompt: 'Generate 3 tasks for a software project',
+  });
+
+  console.log('Generated tasks:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log('✅ Arrays and unions work!\n');
+}
+
+// Test 5: String validations
+async function test5_stringValidations() {
+  console.log('5️⃣  String Validations\n');
+
+  const schema = z.object({
+    email: z.string().email(),
+    url: z.string().url(),
+    uuid: z.string().uuid(),
+    username: z.string().min(3).max(20),
+    description: z.string().max(200),
+  });
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema,
+    prompt: 'Generate a valid user registration with all fields validated',
+  });
+
+  console.log('Generated validated object:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log('✅ String validations work!\n');
+}
+
+// Test 6: Number validations
+async function test6_numberValidations() {
+  console.log('6️⃣  Number Validations\n');
+
+  const schema = z.object({
+    age: z.number().int().min(0).max(120),
+    price: z.number().positive(),
+    discount: z.number().min(0).max(1),
+    rating: z.number().int().min(1).max(5),
+    temperature: z.number().min(-273.15), // Absolute zero
+  });
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema,
+    prompt: 'Generate a product with age restriction, price, discount, rating, and temperature',
+  });
+
+  console.log('Generated validated numbers:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log('✅ Number validations work!\n');
+}
+
+// Test 7: Streaming with Zod 4
+async function test7_streaming() {
+  console.log('7️⃣  Streaming with Zod 4 (text mode)\n');
+
+  const result = streamText({
+    model: claudeCode('opus'),
+    prompt: 'Count from 1 to 5, one number per line',
+  });
+
+  console.log('Streaming response:');
+  for await (const chunk of result.textStream) {
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n✅ Streaming works!\n');
+}
+
+// Test 8: Discriminated unions
+async function test8_discriminatedUnions() {
+  console.log('8️⃣  Discriminated Unions\n');
+
+  const schema = z.object({
+    events: z.array(
+      z.discriminatedUnion('type', [
+        z.object({
+          type: z.literal('login'),
+          userId: z.string(),
+          timestamp: z.string(),
+        }),
+        z.object({
+          type: z.literal('purchase'),
+          userId: z.string(),
+          amount: z.number(),
+          items: z.array(z.string()),
+        }),
+        z.object({
+          type: z.literal('logout'),
+          userId: z.string(),
+          sessionDuration: z.number(),
+        }),
+      ])
+    ),
+  });
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema,
+    prompt: 'Generate 3 different user events: login, purchase, and logout',
+  });
+
+  console.log('Generated discriminated unions:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log('✅ Discriminated unions work!\n');
+}
+
+// Main execution
+async function main() {
+  try {
+    await checkZodVersion();
+    await test1_basicSchemas();
+    await test2_functionSchemas();
+    await test3_nestedObjects();
+    await test4_arraysAndUnions();
+    await test5_stringValidations();
+    await test6_numberValidations();
+    await test7_streaming();
+    await test8_discriminatedUnions();
+
+    console.log('🎉 All Zod 4 compatibility tests passed!\n');
+    console.log('✅ @boostecom/provider is fully compatible with Zod 4\n');
+    console.log('📝 Key changes in Zod 4:');
+    console.log(
+      '   - Function schemas: z.function({ input: [...], output: ... }) instead of .args().returns()'
+    );
+    console.log('   - Better TypeScript inference');
+    console.log('   - Improved error messages');
+    console.log('   - All other Zod features work as expected\n');
+  } catch (error) {
+    console.error('❌ Error:', error);
+    console.log('\n💡 Make sure you have Zod 4.x installed:');
+    console.log('   npm install zod@^4.0.0');
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);