@boostecom/provider 0.0.1

package/docs/src/logger.ts

@@ -0,0 +1,65 @@
+import type { Logger } from './types.js';
+
+/**
+ * Default logger that uses console with level tags.
+ */
+const defaultLogger: Logger = {
+  // eslint-disable-next-line no-console
+  debug: (message: string) => console.debug(`[DEBUG] ${message}`),
+  // eslint-disable-next-line no-console
+  info: (message: string) => console.info(`[INFO] ${message}`),
+  warn: (message: string) => console.warn(`[WARN] ${message}`),
+  error: (message: string) => console.error(`[ERROR] ${message}`),
+};
+
+/**
+ * No-op logger that discards all messages.
+ */
+const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+/**
+ * Gets the appropriate logger based on configuration.
+ *
+ * @param logger - Logger configuration from settings
+ * @returns The logger to use
+ */
+export function getLogger(logger: Logger | false | undefined): Logger {
+  if (logger === false) {
+    return noopLogger;
+  }
+
+  if (logger === undefined) {
+    return defaultLogger;
+  }
+
+  return logger;
+}
+
+/**
+ * Creates a verbose-aware logger that only logs debug/info when verbose is enabled.
+ * Warn and error are always logged regardless of verbose setting.
+ *
+ * @param logger - Base logger to wrap
+ * @param verbose - Whether to enable verbose (debug/info) logging
+ * @returns Logger with verbose-aware behavior
+ */
+export function createVerboseLogger(logger: Logger, verbose: boolean = false): Logger {
+  if (verbose) {
+    // When verbose is enabled, use all log levels
+    return logger;
+  }
+
+  // When verbose is disabled, only allow warn/error
+  // Bind methods to preserve 'this' context for custom loggers
+  return {
+    debug: () => {}, // No-op when not verbose
+    info: () => {}, // No-op when not verbose
+    warn: logger.warn.bind(logger),
+    error: logger.error.bind(logger),
+  };
+}

package/docs/src/map-claude-code-finish-reason.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from 'vitest';
+import { mapClaudeCodeFinishReason } from './map-claude-code-finish-reason.js';
+
+describe('mapClaudeCodeFinishReason', () => {
+  it('should map success to stop with raw value', () => {
+    expect(mapClaudeCodeFinishReason('success')).toEqual({
+      unified: 'stop',
+      raw: 'success',
+    });
+  });
+
+  it('should map error_max_turns to length with raw value', () => {
+    expect(mapClaudeCodeFinishReason('error_max_turns')).toEqual({
+      unified: 'length',
+      raw: 'error_max_turns',
+    });
+  });
+
+  it('should map error_during_execution to error with raw value', () => {
+    expect(mapClaudeCodeFinishReason('error_during_execution')).toEqual({
+      unified: 'error',
+      raw: 'error_during_execution',
+    });
+  });
+
+  it('should map unknown subtypes to other with raw value preserved', () => {
+    expect(mapClaudeCodeFinishReason('unknown_subtype')).toEqual({
+      unified: 'other',
+      raw: 'unknown_subtype',
+    });
+    expect(mapClaudeCodeFinishReason('custom')).toEqual({
+      unified: 'other',
+      raw: 'custom',
+    });
+    expect(mapClaudeCodeFinishReason('')).toEqual({
+      unified: 'other',
+      raw: '',
+    });
+  });
+
+  it('should handle undefined subtype', () => {
+    expect(mapClaudeCodeFinishReason(undefined)).toEqual({
+      unified: 'stop',
+      raw: undefined,
+    });
+  });
+
+  it('should handle null subtype as unknown', () => {
+    expect(mapClaudeCodeFinishReason(null as unknown as string | undefined)).toEqual({
+      unified: 'other',
+      raw: null,
+    });
+  });
+
+  it('should be case sensitive - non-matching cases map to other', () => {
+    expect(mapClaudeCodeFinishReason('Success')).toEqual({
+      unified: 'other',
+      raw: 'Success',
+    });
+    expect(mapClaudeCodeFinishReason('ERROR_MAX_TURNS')).toEqual({
+      unified: 'other',
+      raw: 'ERROR_MAX_TURNS',
+    });
+    expect(mapClaudeCodeFinishReason('Error_During_Execution')).toEqual({
+      unified: 'other',
+      raw: 'Error_During_Execution',
+    });
+  });
+
+  describe('stop_reason support', () => {
+    it('should map end_turn stop_reason to stop', () => {
+      expect(mapClaudeCodeFinishReason('success', 'end_turn')).toEqual({
+        unified: 'stop',
+        raw: 'end_turn',
+      });
+    });
+
+    it('should map max_tokens stop_reason to length', () => {
+      expect(mapClaudeCodeFinishReason('success', 'max_tokens')).toEqual({
+        unified: 'length',
+        raw: 'max_tokens',
+      });
+    });
+
+    it('should map tool_use stop_reason to tool-calls', () => {
+      expect(mapClaudeCodeFinishReason('success', 'tool_use')).toEqual({
+        unified: 'tool-calls',
+        raw: 'tool_use',
+      });
+    });
+
+    it('should map stop_sequence stop_reason to stop', () => {
+      expect(mapClaudeCodeFinishReason('success', 'stop_sequence')).toEqual({
+        unified: 'stop',
+        raw: 'stop_sequence',
+      });
+    });
+
+    it('should fall back to subtype mapping when stop_reason is null', () => {
+      expect(mapClaudeCodeFinishReason('success', null)).toEqual({
+        unified: 'stop',
+        raw: 'success',
+      });
+    });
+
+    it('should fall back to subtype mapping when stop_reason is undefined (backward compat)', () => {
+      expect(mapClaudeCodeFinishReason('error_max_turns', undefined)).toEqual({
+        unified: 'length',
+        raw: 'error_max_turns',
+      });
+    });
+
+    it('should use unknown stop_reason as raw when falling back to subtype mapping', () => {
+      expect(mapClaudeCodeFinishReason('success', 'unknown_reason')).toEqual({
+        unified: 'stop',
+        raw: 'unknown_reason',
+      });
+    });
+  });
+});

package/docs/src/map-claude-code-finish-reason.ts

@@ -0,0 +1,60 @@
+import type { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+
+/**
+ * Maps Claude Code SDK result subtypes to AI SDK finish reasons.
+ *
+ * When `stopReason` is provided (from the SDK's `stop_reason` field), it takes
+ * priority for mapping well-known Anthropic API stop reasons. Otherwise, falls
+ * back to the existing subtype-based mapping.
+ *
+ * @param subtype - The result subtype from Claude Code SDK
+ * @param stopReason - The optional stop_reason from SDKResultSuccess/SDKResultError (v0.2.31+)
+ * @returns The corresponding AI SDK finish reason with unified and raw values
+ *
+ * @example
+ * ```typescript
+ * // With stop_reason (preferred when available)
+ * mapClaudeCodeFinishReason('success', 'end_turn');
+ * // Returns: { unified: 'stop', raw: 'end_turn' }
+ *
+ * // Without stop_reason (backward compatible)
+ * mapClaudeCodeFinishReason('error_max_turns');
+ * // Returns: { unified: 'length', raw: 'error_max_turns' }
+ * ```
+ */
+export function mapClaudeCodeFinishReason(
+  subtype?: string,
+  stopReason?: string | null
+): LanguageModelV3FinishReason {
+  // When stop_reason is present and non-null, map known Anthropic API stop reasons
+  if (stopReason != null) {
+    switch (stopReason) {
+      case 'end_turn':
+        return { unified: 'stop', raw: 'end_turn' };
+      case 'max_tokens':
+        return { unified: 'length', raw: 'max_tokens' };
+      case 'stop_sequence':
+        return { unified: 'stop', raw: 'stop_sequence' };
+      case 'tool_use':
+        return { unified: 'tool-calls', raw: 'tool_use' };
+      default:
+        // Unknown stop_reason: fall back to subtype mapping but preserve stop_reason as raw
+        break;
+    }
+  }
+
+  // Fall back to subtype-based mapping
+  const raw = stopReason ?? subtype;
+  switch (subtype) {
+    case 'success':
+      return { unified: 'stop', raw };
+    case 'error_max_turns':
+      return { unified: 'length', raw };
+    case 'error_during_execution':
+      return { unified: 'error', raw };
+    case undefined:
+      return { unified: 'stop', raw };
+    default:
+      return { unified: 'other', raw };
+  }
+}

package/docs/src/mcp-helpers.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { z } from 'zod';
+
+// Mock the SDK module
+vi.mock('@anthropic-ai/claude-agent-sdk', () => {
+  return {
+    tool: vi.fn((_name, _description, _inputSchema, _handler, _extras) => ({
+      name: _name,
+      description: _description,
+      inputSchema: _inputSchema,
+      handler: _handler,
+      annotations: _extras?.annotations,
+    })),
+    createSdkMcpServer: vi.fn((_options) => ({
+      type: 'sdk' as const,
+      name: _options.name,
+      instance: { tools: _options.tools },
+    })),
+  };
+});
+
+import { tool as mockTool } from '@anthropic-ai/claude-agent-sdk';
+import { createCustomMcpServer } from './mcp-helpers.js';
+import type { ToolAnnotations } from './mcp-helpers.js';
+
+describe('createCustomMcpServer', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should forward annotations to tool() when provided', () => {
+    const annotations: ToolAnnotations = {
+      readOnlyHint: true,
+      destructiveHint: false,
+    };
+
+    createCustomMcpServer({
+      name: 'test-server',
+      tools: {
+        myTool: {
+          description: 'A test tool',
+          inputSchema: z.object({ query: z.string() }),
+          handler: async () => ({ content: [{ type: 'text' as const, text: 'ok' }] }),
+          annotations,
+        },
+      },
+    });
+
+    expect(vi.mocked(mockTool)).toHaveBeenCalledOnce();
+    const callArgs = vi.mocked(mockTool).mock.calls[0];
+    expect(callArgs?.[0]).toBe('myTool');
+    expect(callArgs?.[4]).toEqual({ annotations });
+  });
+
+  it('should pass undefined as 5th arg when annotations are not provided', () => {
+    createCustomMcpServer({
+      name: 'test-server',
+      tools: {
+        plainTool: {
+          description: 'No annotations',
+          inputSchema: z.object({ x: z.number() }),
+          handler: async () => ({ content: [{ type: 'text' as const, text: 'ok' }] }),
+        },
+      },
+    });
+
+    expect(vi.mocked(mockTool)).toHaveBeenCalledOnce();
+    const callArgs = vi.mocked(mockTool).mock.calls[0];
+    expect(callArgs?.[4]).toBeUndefined();
+  });
+});

package/docs/src/mcp-helpers.ts

@@ -0,0 +1,123 @@
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import type {
+  McpSdkServerConfigWithInstance,
+  SdkMcpToolDefinition,
+} from '@anthropic-ai/claude-agent-sdk';
+import { type ZodRawShape, type ZodObject } from 'zod';
+
+/**
+ * Optional annotations for content items, per MCP specification.
+ * Validated against MCP SDK schema version 2025-06-18.
+ */
+type ContentAnnotations = {
+  /** Intended audience(s) for this content */
+  audience?: ('user' | 'assistant')[];
+  /** Priority hint (0 = least important, 1 = most important) */
+  priority?: number;
+  /** ISO 8601 timestamp of last modification */
+  lastModified?: string;
+};
+
+/**
+ * MCP tool annotations for hinting tool behavior to the model.
+ * Derived from the SDK's SdkMcpToolDefinition type to stay in sync
+ * with the upstream MCP ToolAnnotations definition.
+ */
+export type ToolAnnotations = NonNullable<SdkMcpToolDefinition['annotations']>;
+
+/**
+ * Convenience helper to create an SDK MCP server from a simple tool map.
+ * Each tool provides a description, a Zod object schema, and a handler.
+ *
+ * Type definition validated against MCP SDK specification version 2025-06-18.
+ * See: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+ */
+export type MinimalCallToolResult = {
+  content: Array<
+    | {
+        /** Text content */
+        type: 'text';
+        /** The text content (plain text or structured format like JSON) */
+        text: string;
+        annotations?: ContentAnnotations;
+        _meta?: Record<string, unknown>;
+        [key: string]: unknown;
+      }
+    | {
+        /** Image content (base64-encoded) */
+        type: 'image';
+        /** Base64-encoded image data */
+        data: string;
+        /** MIME type of the image (e.g., image/png, image/jpeg) */
+        mimeType: string;
+        annotations?: ContentAnnotations;
+        _meta?: Record<string, unknown>;
+        [key: string]: unknown;
+      }
+    | {
+        /** Audio content (base64-encoded) */
+        type: 'audio';
+        /** Base64-encoded audio data */
+        data: string;
+        /** MIME type of the audio (e.g., audio/wav, audio/mp3) */
+        mimeType: string;
+        annotations?: ContentAnnotations;
+        _meta?: Record<string, unknown>;
+        [key: string]: unknown;
+      }
+    | {
+        /** Embedded resource with full content (text or blob) */
+        type: 'resource';
+        /** Resource contents - either text or blob variant */
+        resource: { uri: string; _meta?: Record<string, unknown>; [key: string]: unknown } & (
+          | { text: string; mimeType?: string }
+          | { blob: string; mimeType: string }
+        );
+        annotations?: ContentAnnotations;
+        _meta?: Record<string, unknown>;
+        [key: string]: unknown;
+      }
+    | {
+        /** Resource link (reference only - no embedded content) */
+        type: 'resource_link';
+        /** URI of the resource */
+        uri: string;
+        /** Human-readable name (required per MCP spec) */
+        name: string;
+        /** Optional description of what this resource represents */
+        description?: string;
+        /** MIME type of the resource, if known */
+        mimeType?: string;
+        annotations?: ContentAnnotations;
+        _meta?: Record<string, unknown>;
+        [key: string]: unknown;
+      }
+  >;
+  isError?: boolean;
+  structuredContent?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+export function createCustomMcpServer<
+  Tools extends Record<
+    string,
+    {
+      description: string;
+      inputSchema: ZodObject<ZodRawShape>;
+      handler: (args: Record<string, unknown>, extra: unknown) => Promise<MinimalCallToolResult>;
+      annotations?: ToolAnnotations;
+    }
+  >,
+>(config: { name: string; version?: string; tools: Tools }): McpSdkServerConfigWithInstance {
+  const defs = Object.entries(config.tools).map(([name, def]) =>
+    tool(
+      name,
+      def.description,
+      def.inputSchema.shape as ZodRawShape,
+      (args: Record<string, unknown>, extra: unknown) => def.handler(args, extra),
+      def.annotations ? { annotations: def.annotations } : undefined
+    )
+  );
+  return createSdkMcpServer({ name: config.name, version: config.version, tools: defs });
+}