@boostecom/provider 0.0.1

package/docs/examples/message-injection.ts

@@ -0,0 +1,210 @@
+/**
+ * Example: Mid-Session Message Injection
+ *
+ * Demonstrates how to inject messages into an active Claude Code session.
+ * Shows stream events to understand when injection can/cannot occur.
+ *
+ * Usage: npx tsx examples/message-injection.ts
+ */
+
+import { streamText } from 'ai';
+import { createClaudeCode } from '../dist/index.js';
+import type { ClaudeCodeSettings, MessageInjector } from '../src/types.js';
+
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+function timestamp() {
+  return `${DIM}[${(performance.now() / 1000).toFixed(2)}s]${RESET}`;
+}
+
+/**
+ * Example 1: Multiple tool calls - injection succeeds
+ */
+async function multipleToolCalls() {
+  console.log(`\n${CYAN}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`${CYAN}  EXAMPLE 1: Multiple Tool Calls${RESET}`);
+  console.log(`${CYAN}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`${DIM}Task: Write 5 files. Inject after 3 seconds.${RESET}\n`);
+
+  let injector: MessageInjector | null = null;
+
+  const defaultSettings: ClaudeCodeSettings = {
+    streamingInput: 'always',
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
+    allowedTools: ['Write'],
+    onStreamStart: (inj: MessageInjector) => {
+      injector = inj;
+      console.log(`${timestamp()} ${GREEN}SESSION STARTED${RESET}`);
+
+      setTimeout(() => {
+        console.log(`${timestamp()} ${YELLOW}>>> INJECT QUEUED: "STOP!"${RESET}`);
+        injector!.inject(
+          'STOP! Do not write more files. Say how many you created.',
+          (delivered) => {
+            console.log(
+              `${timestamp()} ${delivered ? GREEN + '✓ DELIVERED' : RED + '✗ NOT DELIVERED'}${RESET}`
+            );
+          }
+        );
+      }, 3000);
+    },
+  };
+
+  const provider = createClaudeCode({ defaultSettings });
+
+  const result = streamText({
+    model: provider('haiku'),
+    prompt: 'Write 5 files: /tmp/inj-demo/a.txt through e.txt. Each with "hello". One at a time.',
+  });
+
+  let inText = false;
+  for await (const part of result.fullStream) {
+    if (part.type === 'text-delta') {
+      if (!inText) {
+        process.stdout.write(`${timestamp()} ${CYAN}TEXT:${RESET} `);
+        inText = true;
+      }
+      process.stdout.write(part.text);
+    } else if (part.type === 'tool-call') {
+      if (inText) {
+        console.log('');
+        inText = false;
+      }
+      console.log(`${timestamp()} ${CYAN}TOOL-CALL: ${part.toolName}${RESET}`);
+    } else if (part.type === 'tool-result') {
+      console.log(`${timestamp()} ${CYAN}TOOL-RESULT${RESET}`);
+    } else if (part.type === 'finish') {
+      if (inText) {
+        console.log('');
+        inText = false;
+      }
+      console.log(`${timestamp()} ${GREEN}FINISH${RESET}`);
+    }
+  }
+
+  console.log('');
+  const { execSync } = await import('child_process');
+  try {
+    execSync('rm -rf /tmp/inj-demo');
+  } catch {
+    // Cleanup is best-effort, ignore errors
+  }
+}
+
+/**
+ * Example 2: Too late - inject after session ends, then recover
+ */
+async function tooLateWithRecovery() {
+  console.log(`\n${CYAN}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`${CYAN}  EXAMPLE 2: Too Late + Recovery${RESET}`);
+  console.log(`${CYAN}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`${DIM}Task: Quick task. Inject after finish fails, then recover.${RESET}\n`);
+
+  let injector: MessageInjector | null = null;
+  let missedMessage: string | null = null;
+
+  const defaultSettings: ClaudeCodeSettings = {
+    streamingInput: 'always',
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
+    allowedTools: ['Read'],
+    onStreamStart: (inj: MessageInjector) => {
+      injector = inj;
+      console.log(`${timestamp()} ${GREEN}SESSION STARTED${RESET}`);
+    },
+  };
+
+  const provider = createClaudeCode({ defaultSettings });
+
+  const result = streamText({
+    model: provider('haiku'),
+    prompt: 'Read /etc/hosts and say how many lines. Be brief.',
+  });
+
+  let inText = false;
+  for await (const part of result.fullStream) {
+    if (part.type === 'text-delta') {
+      if (!inText) {
+        process.stdout.write(`${timestamp()} ${CYAN}TEXT:${RESET} `);
+        inText = true;
+      }
+      process.stdout.write(part.text);
+    } else if (part.type === 'tool-call') {
+      if (inText) {
+        console.log('');
+        inText = false;
+      }
+      console.log(`${timestamp()} ${CYAN}TOOL-CALL: ${part.toolName}${RESET}`);
+    } else if (part.type === 'tool-result') {
+      console.log(`${timestamp()} ${CYAN}TOOL-RESULT${RESET}`);
+    } else if (part.type === 'finish') {
+      if (inText) {
+        console.log('');
+        inText = false;
+      }
+      console.log(`${timestamp()} ${GREEN}FINISH${RESET}`);
+      // Inject AFTER session ends - too late!
+      const msg = 'What is the first line of /etc/hosts?';
+      console.log(`${timestamp()} ${YELLOW}>>> INJECT QUEUED after finish (too late!)${RESET}`);
+      injector!.inject(msg, (delivered) => {
+        if (!delivered) {
+          console.log(
+            `${timestamp()} ${GREEN}✓ NOT DELIVERED detected - saving for recovery${RESET}`
+          );
+          missedMessage = msg;
+        }
+      });
+    }
+  }
+
+  // Recovery: send missed message as a new turn
+  if (missedMessage) {
+    console.log(
+      `${timestamp()} ${YELLOW}>>> RECOVERING: sending missed message as new prompt${RESET}`
+    );
+    const recovery = streamText({
+      model: provider('haiku'),
+      prompt: missedMessage,
+    });
+    for await (const part of recovery.fullStream) {
+      if (part.type === 'text-delta') {
+        if (!inText) {
+          process.stdout.write(`${timestamp()} ${CYAN}TEXT:${RESET} `);
+          inText = true;
+        }
+        process.stdout.write(part.text);
+      } else if (part.type === 'finish') {
+        if (inText) {
+          console.log('');
+          inText = false;
+        }
+        console.log(`${timestamp()} ${GREEN}FINISH (recovery complete)${RESET}`);
+      }
+    }
+  }
+
+  console.log('');
+}
+
+async function main() {
+  console.log(`${CYAN}Message Injection Examples${RESET}`);
+  console.log(`${DIM}Timestamps show when each event occurs.${RESET}`);
+
+  await multipleToolCalls();
+  await tooLateWithRecovery();
+
+  console.log(`\n${CYAN}═══════════════════════════════════════════════════════════${RESET}`);
+  console.log(`${DIM}The delivery callback lets you know if injection succeeded`);
+  console.log(`or failed, enabling recovery patterns like Example 2.${RESET}\n`);
+}
+
+main().catch((err) => {
+  console.error('Example failed:', err);
+  process.exit(1);
+});

package/docs/examples/mid-stream-injection.ts

@@ -0,0 +1,126 @@
+/**
+ * Mid-stream injection example for Claude Code AI SDK Provider.
+ *
+ * This example shows how to re-steer a running query by sending an
+ * additional user message via the underlying Query object.
+ */
+
+import { streamText } from 'ai';
+import type { CanUseTool } from '@anthropic-ai/claude-agent-sdk';
+import { claudeCode, type Query } from '../dist/index.js';
+
+type SdkUserMessage = {
+  type: 'user';
+  message: {
+    role: 'user';
+    content: Array<{ type: 'text'; text: string }>;
+  };
+  parent_tool_use_id: null;
+  session_id: string;
+};
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const toSdkUserMessage = (text: string, sessionId = ''): SdkUserMessage => ({
+  type: 'user',
+  message: {
+    role: 'user',
+    content: [{ type: 'text', text }],
+  },
+  parent_tool_use_id: null,
+  session_id: sessionId,
+});
+
+async function* singleMessage(text: string, sessionId = '') {
+  yield toSdkUserMessage(text, sessionId);
+}
+
+const allowAllTools: CanUseTool = async (_toolName, input) => ({
+  behavior: 'allow',
+  updatedInput: input,
+});
+
+async function main() {
+  let activeQuery: Query | undefined;
+  let injected = false;
+  let streamedChars = 0;
+  let sessionId: string | undefined;
+
+  const tryInject = async () => {
+    if (injected || !activeQuery) return;
+    injected = true;
+    await sleep(400);
+
+    try {
+      await activeQuery.streamInput(
+        singleMessage(
+          'Mid-stream update: switch to nautical metaphors and add a short 3-bullet list of benefits.',
+          sessionId ?? ''
+        )
+      );
+      console.log('\n\n[Injected a mid-stream update]\n');
+    } catch (error) {
+      console.error('\n[Failed to inject mid-stream update]', error);
+    }
+  };
+
+  const model = claudeCode('sonnet', {
+    streamingInput: 'always',
+    canUseTool: allowAllTools,
+    permissionMode: 'bypassPermissions',
+    allowedTools: ['Bash'],
+    cwd: process.cwd(),
+    onQueryCreated: (query) => {
+      activeQuery = query;
+      void tryInject();
+    },
+  });
+
+  const result = streamText({
+    model,
+    prompt:
+      'Write the first paragraph of a product pitch for a coffee subscription. Then run the Bash command `sleep 2` before continuing with the remaining paragraph. Be upbeat and detailed.',
+  });
+
+  console.log('--- Streaming response (watch for the tone shift) ---\n');
+
+  const stream = result.fullStream as AsyncIterable<unknown>;
+
+  for await (const part of stream) {
+    if (!part || typeof part !== 'object') continue;
+    const typed = part as {
+      type?: string;
+      id?: string;
+      delta?: unknown;
+      text?: unknown;
+    };
+
+    if (typed.type === 'response-metadata') {
+      sessionId = typed.id;
+      void tryInject();
+    }
+
+    if (typed.type === 'tool-call') {
+      void tryInject();
+    }
+
+    if (typed.type === 'text-delta') {
+      const chunk = typed.delta ?? typed.text;
+      if (typeof chunk === 'string') {
+        process.stdout.write(chunk);
+        streamedChars += chunk.length;
+
+        if (streamedChars > 200) {
+          void tryInject();
+        }
+      }
+    }
+  }
+
+  console.log('\n');
+}
+
+main().catch((error) => {
+  console.error('Example failed:', error);
+  process.exitCode = 1;
+});

package/docs/examples/run-all-examples.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Build once
+echo "Building project..."
+npm run build
+
+# List of all examples
+examples=(
+  "basic-usage"
+  "streaming"
+  "conversation-history"
+  "custom-config"
+  "generate-object"
+  "generate-object-constraints"
+  "tool-management"
+  "long-running-tasks"
+  "abort-signal"
+  "check-cli"
+  "integration-test"
+  "limitations"
+  "hooks-callbacks"
+  "sdk-tools-callbacks"
+  "tool-streaming"
+  "images"
+)
+
+# Run each example
+for example in "${examples[@]}"; do
+  echo ""
+  echo "========================================="
+  echo "Running: $example.ts"
+  echo "========================================="
+
+  # images.ts optionally accepts a path argument
+  if [ "$example" = "images" ] && [ -n "$EXAMPLE_IMAGE_PATH" ]; then
+    npx tsx "examples/$example.ts" "$EXAMPLE_IMAGE_PATH"
+  else
+    npx tsx "examples/$example.ts"
+  fi
+
+  # Check if the command succeeded
+  if [ $? -ne 0 ]; then
+    echo "❌ Failed: $example.ts"
+  fi
+done
+
+echo ""
+echo "✅ All examples completed!"

package/docs/examples/sdk-tools-callbacks.ts

@@ -0,0 +1,49 @@
+/**
+ * Example: SDK MCP Tools (callbacks)
+ *
+ * Demonstrates defining in-process tools via createSdkMcpServer and tool,
+ * wiring them to the provider via mcpServers, and constraining access
+ * via allowedTools.
+ */
+
+import { z } from 'zod';
+import { streamText } from 'ai';
+import { createClaudeCode, createSdkMcpServer, tool } 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']
+
+// Define an in-process tool
+const add = tool('add', 'Add two numbers', { a: z.number(), b: z.number() }, async ({ a, b }) => ({
+  content: [{ type: 'text', text: String(a + b) }],
+}));
+
+// Create SDK MCP server
+const sdkServer = createSdkMcpServer({ name: 'local', tools: [add] });
+
+async function main() {
+  // Wire the MCP server and restrict to this tool
+  const provider = createClaudeCode({
+    defaultSettings: {
+      mcpServers: { local: sdkServer },
+      allowedTools: ['mcp__local__add'],
+    },
+  });
+
+  const result = streamText({
+    model: provider('opus'),
+    prompt: 'Use the add tool to sum 3 and 4. Provide only the number.',
+  });
+
+  let text = '';
+  for await (const chunk of result.textStream) text += chunk;
+  console.log('Response:', text.trim());
+}
+
+main().catch((err) => {
+  console.error('Example failed:', err);
+  process.exit(1);
+});

package/docs/examples/skills-discovery.ts

@@ -0,0 +1,144 @@
+import { claudeCode } from '../dist/index.js';
+import { generateText } from 'ai';
+
+/**
+ * Skills Discovery Example
+ * 
+ * Demonstrates how to programmatically discover and use available Skills
+ * in your Claude Code environment. This is useful for:
+ * - Building dynamic UIs that show available capabilities
+ * - Validating Skills are properly loaded
+ * - Testing Skills configuration
+ * - Creating Skills marketplaces or directories
+ */
+
+async function main() {
+  console.log('=== Skills Discovery Example ===\n');
+
+  // Create a model with Skills enabled
+  const model = claudeCode('sonnet', {
+    // Load Skills from filesystem
+    settingSources: ['user', 'project'],
+    
+    // Enable Skill tool
+    allowedTools: ['Skill'],
+    
+    verbose: true,
+  });
+
+  try {
+    // Ask Claude to list available Skills
+    console.log('Discovering available Skills...\n');
+
+    const { text } = await generateText({
+      model,
+      prompt: `Please list all available Skills you have access to. For each Skill, provide:
+1. The Skill name
+2. A brief description of what it does
+3. When it would be useful to invoke it
+
+Format your response as a structured list.`,
+    });
+
+    console.log('=== Available Skills ===');
+    console.log(text);
+    console.log('\n');
+
+    // Test specific Skill invocation
+    console.log('=== Testing Skill Invocation ===\n');
+    
+    const skillTest = await generateText({
+      model: claudeCode('haiku', {
+        settingSources: ['user', 'project'],
+        allowedTools: ['Skill', 'Read'],
+      }),
+      prompt: 'Can you show me an example of using a Skill? Pick any available Skill and demonstrate it.',
+    });
+
+    console.log(skillTest.text);
+
+  } catch (error) {
+    console.error('Error:', error);
+    
+    if (error instanceof Error && error.message.includes('settingSources')) {
+      console.error('\nTip: Make sure you have Skills configured in:');
+      console.error('  - User Skills: ~/.claude/skills/');
+      console.error('  - Project Skills: ./.claude/skills/');
+      console.error('\nYou need to set settingSources to load Skills from filesystem.');
+    }
+  }
+}
+
+/**
+ * Advanced: Validate Skills Configuration
+ * 
+ * This function demonstrates how to validate that Skills are
+ * properly configured and accessible.
+ */
+async function validateSkillsSetup() {
+  console.log('\n=== Validating Skills Setup ===\n');
+
+  const configs = [
+    {
+      name: 'Without settingSources',
+      settings: { allowedTools: ['Skill'] },
+      expectedBehavior: 'Skills NOT loaded',
+    },
+    {
+      name: 'With user settingSources',
+      settings: { settingSources: ['user'], allowedTools: ['Skill'] },
+      expectedBehavior: 'User Skills loaded',
+    },
+    {
+      name: 'With project settingSources',
+      settings: { settingSources: ['project'], allowedTools: ['Skill'] },
+      expectedBehavior: 'Project Skills loaded',
+    },
+    {
+      name: 'With both settingSources',
+      settings: { settingSources: ['user', 'project'], allowedTools: ['Skill'] },
+      expectedBehavior: 'All Skills loaded',
+    },
+  ] as const;
+
+  for (const config of configs) {
+    console.log(`Testing: ${config.name}`);
+    console.log(`Expected: ${config.expectedBehavior}`);
+    
+    try {
+      const model = claudeCode('haiku', config.settings as any);
+      
+      const { text } = await generateText({
+        model,
+        prompt: 'List available Skills. If none, say "No Skills available".',
+        maxTokens: 200,
+      });
+
+      const hasSkills = !text.toLowerCase().includes('no skills');
+      console.log(`Result: ${hasSkills ? 'Skills found' : 'No Skills'}`);
+      console.log(`Sample: ${text.slice(0, 100)}...\n`);
+      
+    } catch (error) {
+      console.log(`Error: ${error instanceof Error ? error.message : 'Unknown error'}\n`);
+    }
+  }
+}
+
+// Run main example
+main()
+  .then(() => {
+    // Optionally run validation
+    if (process.argv.includes('--validate')) {
+      return validateSkillsSetup();
+    }
+  })
+  .catch(console.error);
+
+/**
+ * Usage:
+ * 
+ * npm run build && npx tsx examples/skills-discovery.ts
+ * 
+ * Or with validation:
+ * npm run build && npx tsx examples/skills-discovery.ts --validate
+ */