@raindrop-ai/wizard 0.0.1

package/dist/src/docs/vercel-ai-sdk.md

@@ -0,0 +1,304 @@
+## Vercel AI SDK Integration
+
+Two-step setup:
+
+1. Configure OpenTelemetry trace exporter (platform-specific)
+2. Instrument AI SDK calls with Raindrop metadata
+
+---
+
+## Step 1: Configure OTEL Trace Exporter
+
+> Choose the section matching the project setup:
+>
+> - **Next.js + Sentry** → [With Sentry (Next.js)](#with-sentry-nextjs)
+> - **Next.js (no Sentry)** → [Next.js](#nextjs)
+> - **Node.js** → [Node.js](#nodejs)
+> - **Cloudflare Workers** → [Cloudflare Workers](#cloudflare-workers)
+
+### With Sentry (Next.js)
+
+If already using Sentry, add Raindrop's exporter to Sentry's OTEL config to
+avoid duplicate registration issues.
+
+**Install dependencies:**
+
+```bash
+npm install @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-base
+```
+
+**Configure:**
+
+```ts
+// sentry.server.config.ts
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  tracesSampleRate: 1,
+  openTelemetrySpanProcessors: [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: 'https://api.raindrop.ai/v1/traces',
+        headers: {
+          Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
+        },
+      }),
+    ),
+  ],
+});
+```
+
+### Next.js
+
+**Install dependencies:**
+
+```bash
+npm install raindrop-ai @opentelemetry/api @opentelemetry/sdk-trace-base @vercel/otel
+```
+
+**Configure:**
+
+```ts
+// instrumentation.ts
+import { registerOTel, OTLPHttpProtoTraceExporter } from '@vercel/otel';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+export function register() {
+  registerOTel({
+    serviceName: projectName, // Replace with your app/service name
+    spanProcessors: [
+      new BatchSpanProcessor(
+        new OTLPHttpProtoTraceExporter({
+          url: 'https://api.raindrop.ai/v1/traces',
+          headers: {
+            Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
+          },
+        }),
+      ),
+    ],
+  });
+}
+```
+
+> Error: "Cannot execute the operation on ended Span" → Use `runtime = 'nodejs'`
+> instead of `'edge'`.
+
+### Node.js
+
+**Install dependencies:**
+
+```bash
+npm install raindrop-ai @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-node
+```
+
+**Configure:**
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: projectName, // Replace with your app/service name
+  }),
+  spanProcessors: [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: 'https://api.raindrop.ai/v1/traces',
+        headers: {
+          Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
+        },
+      }),
+    ),
+  ],
+});
+
+sdk.start();
+```
+
+### Cloudflare Workers
+
+Cloudflare's native tracing does not support custom spans. Use
+`@microlabs/otel-cf-workers`.
+
+**Install dependencies:**
+
+```bash
+npm install raindrop-ai @opentelemetry/api @microlabs/otel-cf-workers
+```
+
+**Wrangler config:**
+
+```toml
+compatibility_flags = ["nodejs_compat"]
+```
+
+**OTEL config:**
+
+```ts
+// src/otel.ts
+import { instrument, type ResolveConfigFn } from '@microlabs/otel-cf-workers';
+
+export interface Env {
+  RAINDROP_WRITE_KEY: string;
+  [key: string]: unknown;
+}
+
+export const otelConfig: ResolveConfigFn<Env> = (env, _trigger) => ({
+  exporter: {
+    url: 'https://api.raindrop.ai/v1/traces',
+    headers: {
+      Authorization: `Bearer ${env.RAINDROP_WRITE_KEY}`,
+    },
+  },
+  service: {
+    name: workerName, // Replace with your worker/service name
+  },
+});
+
+export { instrument };
+```
+
+**Instrument handler:**
+
+```ts
+// src/index.ts — adapt AI provider imports to your project
+import { streamText } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai'; // Adapt to your AI provider (e.g. @ai-sdk/anthropic)
+import raindrop from 'raindrop-ai/otel';
+import { instrument, otelConfig, Env } from './otel';
+
+const handler = {
+  async fetch(
+    request: Request,
+    env: Env,
+    ctx: ExecutionContext,
+  ): Promise<Response> {
+    const openai = createOpenAI({ apiKey: env.OPENAI_API_KEY }); // Adapt to your AI provider
+    const { prompt } = await request.json();
+
+    const result = streamText({
+      model: model, // Your app's AI model instance (e.g. 'gpt-4o','claude-3-opus')
+      prompt,
+      experimental_telemetry: {
+        isEnabled: true,
+        functionId: 'chat',
+        metadata: {
+          ...raindrop.metadata({ userId: userId }), // The authenticated user's ID from your app
+        },
+      },
+    });
+
+    ctx.waitUntil(result.text);
+    return result.toTextStreamResponse();
+  },
+};
+
+export default instrument(handler, otelConfig);
+```
+
+---
+
+## Step 2: Instrumentation
+
+### Requirements
+
+1. Enable telemetry at **all** AI SDK call sites:
+   `experimental_telemetry: { isEnabled: true }`
+2. Add Raindrop metadata at top-level call using `raindrop.metadata()`
+
+### Usage
+
+```typescript
+// Adapt imports to your project's AI provider (e.g. @ai-sdk/openai, @ai-sdk/anthropic, etc.)
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+import raindrop from 'raindrop-ai/otel';
+
+// Nested call - only needs isEnabled: true
+const enhanceStory = tool({
+  description: 'Enhance story',
+  parameters: z.object({ story: z.string() }),
+  execute: async ({ story }) => {
+    const enhanced = await generateText({
+      model: model, // Your app's AI model instance (e.g. 'gpt-4o','claude-3-opus')
+      prompt: `Enhance: ${story}`,
+      experimental_telemetry: {
+        isEnabled: true, // Required at all call sites
+        functionId: 'enhance-story',
+      },
+    });
+    return { enhancedStory: enhanced.text };
+  },
+});
+
+// Top-level call - add raindrop.metadata()
+const result = await generateText({
+  model: model, // Your app's AI model instance
+  prompt: userPrompt,
+  tools: { enhanceStory },
+  experimental_telemetry: {
+    isEnabled: true, // Required
+    functionId: 'generate-text',
+    metadata: {
+      ...raindrop.metadata({
+        userId: userId, // Required — the authenticated user's ID from your app
+        eventName: eventName, // A descriptive name for this AI action (e.g. 'chat_message', 'code_generation')
+        convoId: conversationId, // Your app's conversation/thread ID (if applicable)
+        wizardSession: '__WIZARD_SESSION_UUID__', // Required
+      }),
+    },
+  },
+});
+```
+
+### Key Points
+
+- **All call sites** need `experimental_telemetry: { isEnabled: true }`
+- **Top-level call** adds `raindrop.metadata()` to capture user/event info
+- **Nested calls** only need `isEnabled: true`
+
+## Troubleshooting
+
+### Debug Logging
+
+```bash
+OTEL_LOG_LEVEL=debug npm run dev
+```
+
+### Missing Traces
+
+Ensure `experimental_telemetry: { isEnabled: true }` at **every** AI SDK call:
+
+```typescript
+// ❌ Not traced
+const result = await generateText({ model: openai('gpt-4o'), prompt: 'Hello' });
+
+// ✅ Traced
+const result = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello',
+  experimental_telemetry: { isEnabled: true },
+});
+```
+
+### Cloudflare Workers: Incomplete Spans
+
+Streaming responses need `waitUntil()` to prevent premature flush:
+
+```typescript
+// ❌ Incomplete spans (1ms duration)
+const result = streamText({ ... });
+return result.toTextStreamResponse();
+
+// ✅ Complete spans
+const result = streamText({ ... });
+ctx.waitUntil(result.text);  // Delays flush until stream completes
+return result.toTextStreamResponse();
+```

package/dist/src/lib/agent-interface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared agent interface for  wizards
+ * Uses Claude Agent SDK directly with streaming input support
+ */
+import type { AgentQueryHandle } from '../ui/types.js';
+import type { WizardOptions } from '../utils/types.js';
+export type { AgentQueryHandle };
+export type AgentConfig = {
+    workingDirectory: string;
+};
+/**
+ * Result from runAgentLoop including session ID and query handle
+ */
+export interface AgentRunResult {
+    sessionId?: string;
+    handle: AgentQueryHandle;
+}
+/**
+ * Internal configuration object returned by initializeAgent
+ */
+export type AgentRunConfig = {
+    workingDirectory: string;
+    model: string;
+};
+/**
+ * Initialize agent configuration for the Claude agent
+ */
+export declare function initializeAgent(config: AgentConfig, options: WizardOptions): AgentRunConfig;
+/**
+ * Configuration for runAgentLoop
+ */
+export interface RunAgentConfig {
+    spinnerMessage?: string;
+    successMessage?: string;
+    resume?: string;
+    accessToken: string;
+    orgId: string;
+}
+/**
+ * Execute an agent with the provided prompt and options.
+ * Supports streaming input for user interruption and follow-up messages.
+ * Uses a while loop to handle user interactions instead of recursion.
+ *
+ * @returns Session ID and query handle for controlling the agent
+ */
+export declare function runAgentLoop(agentConfig: AgentRunConfig, prompt: string, options: WizardOptions, config?: RunAgentConfig): Promise<AgentRunResult>;

package/dist/src/lib/agent-interface.js

@@ -0,0 +1,292 @@
+/**
+ * Shared agent interface for  wizards
+ * Uses Claude Agent SDK directly with streaming input support
+ */
+import path from 'path';
+import { createRequire } from 'module';
+import ui from '../utils/ui.js';
+import { debug, logToFile, initLogFile, LOG_FILE_PATH, } from '../utils/debug.js';
+import { createCanUseToolHandler, createAgentQueryHandle, } from './handlers.js';
+import { processSDKMessage } from './sdk-messages.js';
+import { createCompletionMcpServer } from './mcp.js';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+// Create a require function for ESM compatibility
+const require = createRequire(import.meta.url);
+/**
+ * Get the path to the bundled Claude Code CLI from the SDK package.
+ * This ensures we use the SDK's bundled version rather than the user's installed Claude Code.
+ */
+function getClaudeCodeExecutablePath() {
+    // require.resolve finds the package's main entry, then we get cli.js from same dir
+    const sdkPackagePath = require.resolve('@anthropic-ai/claude-agent-sdk');
+    return path.join(path.dirname(sdkPackagePath), 'cli.js');
+}
+/**
+ * Initialize agent configuration for the Claude agent
+ */
+export function initializeAgent(config, options) {
+    // Initialize log file for this run
+    initLogFile();
+    logToFile('Agent initialization starting');
+    logToFile('Install directory:', options.installDir);
+    try {
+        process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 'true';
+        // Set default subagent model to Sonnet
+        process.env.CLAUDE_CODE_SUBAGENT_MODEL = 'claude-sonnet-4-5-20250929';
+        const agentRunConfig = {
+            workingDirectory: config.workingDirectory,
+            model: 'opus',
+        };
+        logToFile('Agent config:', {
+            workingDirectory: agentRunConfig.workingDirectory,
+        });
+        if (options.debug) {
+            debug('Agent config:', {
+                workingDirectory: agentRunConfig.workingDirectory,
+            });
+        }
+        ui.addItem({
+            type: 'step',
+            text: `I'll keep verbose logs for this session at: ${LOG_FILE_PATH}`,
+        });
+        return agentRunConfig;
+    }
+    catch (error) {
+        ui.addItem({
+            type: 'error',
+            text: `Failed to initialize agent: ${error.message}`,
+        });
+        logToFile('Agent initialization error:', error);
+        debug('Agent initialization error:', error);
+        throw error;
+    }
+}
+/**
+ * Execute an agent with the provided prompt and options.
+ * Supports streaming input for user interruption and follow-up messages.
+ * Uses a while loop to handle user interactions instead of recursion.
+ *
+ * @returns Session ID and query handle for controlling the agent
+ */
+export async function runAgentLoop(agentConfig, prompt, options, config) {
+    const { spinnerMessage = 'Raindrop wizard is working...', successMessage = 'Raindrop integration complete', resume, accessToken, } = config ?? {};
+    // Add header to indicate start of interactive agent phase
+    ui.addItem({ type: 'phase', text: '─── Agent ───' });
+    const cliPath = getClaudeCodeExecutablePath();
+    logToFile('Starting agent run');
+    logToFile('Claude Code executable:', cliPath);
+    // Loop-persistent state
+    let currentPrompt = prompt;
+    let currentSessionId = resume;
+    let handle;
+    // Cache for approved files (persists across all iterations)
+    const approvedFilesCache = new Set();
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const spinner = ui.spinner();
+        logToFile('Prompt:', currentPrompt);
+        if (currentSessionId) {
+            logToFile('Resuming session:', currentSessionId);
+        }
+        // Timing and session state
+        const startTime = Date.now();
+        let sessionId = currentSessionId;
+        let queryObject = null;
+        // Message and tool call collectors
+        const collectedText = [];
+        const pendingToolCalls = new Map();
+        // Shared ref objects for cross-boundary state
+        const hasCompletedWorkRef = { value: false };
+        const isInterruptingRef = { value: false };
+        const waitingForUserInputRef = { value: false };
+        const pendingUserMessageRef = { value: null };
+        const exitHintShownRef = { value: false };
+        // Promise resolver for waiting on user input after interrupt
+        let resolveUserMessage = null;
+        // Query handle for external control (interrupt, etc.)
+        handle = createAgentQueryHandle({
+            isInterruptingRef,
+            waitingForUserInputRef,
+            pendingToolCalls,
+            getQueryObject: () => queryObject,
+        });
+        // Create MCP server with CompleteIntegration tool
+        const completionMcpServer = createCompletionMcpServer(hasCompletedWorkRef, {
+            sessionId: options.sessionId,
+            accessToken,
+            orgId: config?.orgId ?? '',
+            installDir: agentConfig.workingDirectory,
+        });
+        // Define callbacks for persistent input
+        const handlePersistentSubmit = (message) => {
+            // Reset exit hint flag when user submits a message
+            exitHintShownRef.value = false;
+            if (isInterruptingRef.value) {
+                // Already interrupted - resolve the waiting promise with this message
+                logToFile('User submitted message after interrupt:', message);
+                pendingUserMessageRef.value = message;
+                if (resolveUserMessage) {
+                    resolveUserMessage(message);
+                    resolveUserMessage = null;
+                }
+            }
+            else {
+                // Not yet interrupted - store message and trigger interrupt
+                pendingUserMessageRef.value = message;
+                logToFile('User submitted message while agent running - triggering interrupt');
+                void handle.interrupt();
+            }
+        };
+        const handlePersistentInterrupt = () => {
+            logToFile('User requested interrupt (Esc)');
+            // Stop spinner immediately - persistent input stays visible
+            spinner.stop();
+            void handle.interrupt();
+        };
+        const handlePersistentCtrlC = () => {
+            logToFile('User pressed Ctrl+C');
+            // If already interrupted and exit hint was shown, exit immediately
+            if ((isInterruptingRef.value || waitingForUserInputRef.value) &&
+                exitHintShownRef.value) {
+                logToFile('Second Ctrl+C - exiting');
+                ui.stopPersistentInput();
+                ui.exit();
+                // Small delay to allow UI to clean up before exit
+                setTimeout(() => process.exit(130), 100);
+                return;
+            }
+            // If already interrupted but hint not shown yet, show hint and clear input
+            if (isInterruptingRef.value || waitingForUserInputRef.value) {
+                logToFile('First Ctrl+C while interrupted - showing exit hint');
+                exitHintShownRef.value = true;
+                // Clear the input and update placeholder with hint
+                ui.stopPersistentInput();
+                ui.startPersistentInput({
+                    onSubmit: handlePersistentSubmit,
+                    onInterrupt: handlePersistentInterrupt,
+                    onCtrlC: handlePersistentCtrlC,
+                    placeholder: 'Press Ctrl+C again to exit',
+                });
+                return;
+            }
+            // Not interrupted yet - treat as normal interrupt
+            logToFile('First Ctrl+C - triggering interrupt');
+            spinner.stop();
+            void handle.interrupt();
+        };
+        spinner.start(spinnerMessage);
+        ui.startPersistentInput({
+            onSubmit: handlePersistentSubmit,
+            onInterrupt: handlePersistentInterrupt,
+            onCtrlC: handlePersistentCtrlC,
+        });
+        // Session info for notifications
+        const sessionInfo = {
+            sessionId: options.sessionId,
+            accessToken,
+            orgId: config?.orgId ?? '',
+        };
+        queryObject = query({
+            prompt: currentPrompt,
+            options: {
+                model: agentConfig.model,
+                cwd: agentConfig.workingDirectory,
+                permissionMode: 'default',
+                mcpServers: {
+                    'raindrop-wizard': completionMcpServer,
+                },
+                systemPrompt: '{WIZARD_SYSTEM_PROMPT}',
+                env: { ...process.env },
+                resume: currentSessionId,
+                canUseTool: createCanUseToolHandler(sessionInfo, approvedFilesCache),
+                stderr: (data) => {
+                    logToFile('CLI stderr:', data);
+                    if (options.debug) {
+                        debug('CLI stderr:', data);
+                    }
+                },
+            },
+        });
+        // Update agent state
+        ui.setAgentState({
+            isRunning: true,
+            queryHandle: handle,
+        });
+        // Process the query stream
+        for await (const message of queryObject) {
+            // FIX: Check interrupt flag at start of each iteration
+            // This handles the case where interrupt() was called before SDK initialized
+            if (isInterruptingRef.value) {
+                logToFile('Breaking out of for-await loop - interrupt flag set before SDK init');
+                // Capture session_id from init message if available before breaking
+                if (message.session_id && !sessionId) {
+                    sessionId = message.session_id;
+                    ui.setAgentState({ sessionId });
+                }
+                break;
+            }
+            // Capture session_id from any message
+            if (message.session_id && !sessionId) {
+                sessionId = message.session_id;
+                ui.setAgentState({ sessionId });
+            }
+            processSDKMessage(message, options, collectedText, pendingToolCalls, isInterruptingRef.value);
+        }
+        const durationMs = Date.now() - startTime;
+        logToFile(`Agent run completed in ${Math.round(durationMs / 1000)}s`);
+        logToFile('Session ID for resuming:', sessionId);
+        logToFile('Completion status:', hasCompletedWorkRef.value);
+        // Check if we need user input to continue (either stream ended without completion or interrupted)
+        const needsUserInput = !hasCompletedWorkRef.value && !waitingForUserInputRef.value && sessionId;
+        const wasInterrupted = waitingForUserInputRef.value && sessionId;
+        if (needsUserInput || wasInterrupted) {
+            if (needsUserInput) {
+                logToFile('Stream ended but agent has not called CompleteIntegration - waiting for user response');
+            }
+            else {
+                logToFile('Stream ended after interrupt, waiting for user input');
+            }
+            spinner.stop();
+            ui.setAgentState({ isRunning: false });
+            // Get the resume message - either from pending submit or wait for user to submit
+            let userMessage;
+            if (pendingUserMessageRef.value) {
+                // Message was submitted during execution - use it directly
+                userMessage = pendingUserMessageRef.value;
+                pendingUserMessageRef.value = null; // Clear for next iteration
+                logToFile('Using pending user message:', userMessage);
+            }
+            else {
+                // No pending message - wait for user to submit via persistent input
+                logToFile('Waiting for user to submit message via persistent input...');
+                // Persistent input is already visible, spinner already stopped - just wait for user
+                userMessage = await new Promise((resolve) => {
+                    resolveUserMessage = resolve;
+                });
+                // Check if user cancelled (empty message from Esc)
+                if (!userMessage) {
+                    logToFile('User cancelled input, ending session');
+                    ui.stopPersistentInput();
+                    return { sessionId, handle };
+                }
+                logToFile('Received user message from persistent input:', userMessage);
+            }
+            // Show user message in UI
+            ui.addItem({
+                type: 'user-message',
+                text: userMessage,
+            });
+            // Update state for next iteration
+            logToFile('Resuming agent with user message:', userMessage);
+            currentPrompt = userMessage;
+            currentSessionId = sessionId;
+            continue;
+        }
+        // Normal completion - clean up and return
+        ui.stopPersistentInput();
+        ui.setAgentState({ isRunning: false });
+        spinner.stop(successMessage);
+        return { sessionId, handle };
+    }
+}
+//# sourceMappingURL=agent-interface.js.map