@raindrop-ai/wizard 0.0.9 → 0.0.11

package/dist/src/docs/claude-agent-sdk.mdx

@@ -53,6 +53,7 @@ const { query, createSdkMcpServer, ReadTool, EditTool } = raindrop.wrap(
         wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
       },
     },
+    selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
   },
 );
 
@@ -126,9 +127,85 @@ const wrapped = raindrop.wrap(claudeAgentSDK, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 ```
 
+### Self Diagnostics
+
+Enabling `selfDiagnostics` injects a tool that allows the users' AI to report
+issues it detects during execution (for example: tool failures, looping
+behavior, or missing capabilities). The tool is delivered as an in-process MCP
+server, so it works alongside any other MCP servers the user configures. The
+tool name defaults to `__raindrop_report`, and can be overridden with
+`selfDiagnostics.toolName`. The SDK automatically prompt-engineers the tool
+description from the developer provided `signals` definitions;
+`selfDiagnostics.guidance` is optional extra guidance.
+
+```typescript
+import * as claudeAgentSDK from '@anthropic-ai/claude-agent-sdk';
+import {
+  createRaindropClaudeAgentSDK,
+  eventMetadata,
+} from '@raindrop-ai/claude-agent-sdk';
+
+const raindrop = createRaindropClaudeAgentSDK({
+  writeKey: process.env.RAINDROP_WRITE_KEY!,
+});
+
+const wrapped = raindrop.wrap(claudeAgentSDK, {
+  context: {
+    properties: {
+      wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+    },
+  },
+  selfDiagnostics: {
+    enabled: true,
+    // Optional: replace defaults with domain-specific categories
+    signals: {
+      missing_context: {
+        description:
+          'You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. ' +
+          'Do NOT report this for normal clarifying questions — only when you are blocked.',
+        sentiment: 'NEGATIVE',
+      },
+      repeatedly_broken_tool: {
+        description:
+          'A tool has failed or not returned the expected response on multiple distinct attempts in this conversation, preventing task completion. ' +
+          'A single tool error is NOT enough — the tool must be persistently broken or aberrantly behaving across retries.',
+        sentiment: 'NEGATIVE',
+      },
+      complete_task_failure: {
+        description:
+          'You were unable to accomplish what the user asked despite making genuine attempts. ' +
+          'This is NOT a refusal or policy block — you tried and failed to deliver the result.',
+        sentiment: 'NEGATIVE',
+      },
+    },
+  },
+});
+```
+
+When invoked, the injected tool tracks a signal on the same `eventId`:
+
+```json
+{
+  "event_id": "evt_...",
+  "signal_name": "agent:tool_failure",
+  "signal_type": "agent",
+  "properties": {
+    "source": "agent_reporting_tool",
+    "category": "tool_failure",
+    "signal_description": "A tool call returned an error, timed out, or produced unusable output.",
+    "detail": "The search API returned a 503 after two retries."
+  }
+}
+```
+
+The self-diagnostics tool is invisible: it is auto-approved in the PreToolUse
+hook and its tool_use/tool_result blocks are stripped from the SDK stream, so
+the user never sees it and doesn't need to handle it.
+
 ## Per-Query Context
 
 Use `eventMetadata()` as the second argument when you want a query tracked.
@@ -143,6 +220,7 @@ const wrapped = raindrop.wrap(claudeAgentSDK, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 for await (const msg of wrapped.query(
@@ -201,6 +279,7 @@ const wrapped = raindrop.wrap(claudeAgentSDK, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 for await (const msg of wrapped.query(
@@ -257,6 +336,7 @@ const wrapped = raindrop.wrap(claudeAgentSDK, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 for await (const msg of wrapped.query(
@@ -310,6 +390,7 @@ export async function POST(request: Request) {
         wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
       },
     },
+    selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
   });
   const messages = [];
   for await (const msg of wrapped.query(

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

@@ -50,6 +50,7 @@ const { generateText, streamText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 // 3. Use the wrapped methods
@@ -156,6 +157,7 @@ const { generateText } = raindrop.wrap(ai, {
     }, // Optional - custom metadata
     attachments: [], // Optional - input/output attachments
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 
   autoAttachment: true, // Default: true. Set false to disable automatic parsing
 
@@ -199,6 +201,7 @@ const { generateText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 // Override defaults for this call
@@ -242,6 +245,7 @@ const { generateText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 await generateText({
@@ -299,6 +303,7 @@ const { generateText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 // Tool calls are traced with args and results
@@ -317,6 +322,56 @@ const result = await generateText({
 });
 ```
 
+### Self Diagnostics
+
+Enabling `selfDiagnostics` injects a hidden tool that the user's AI can call
+silently when it hits an unrecoverable problem. Signals appear in Raindrop's
+Self Diagnostics section and feed into issue discovery.
+
+The three default categories are `missing_context`, `repeatedly_broken_tool`,
+and `complete_task_failure`. You can replace these with your own.
+
+```typescript
+const { generateText } = raindrop.wrap(ai, {
+  // Optional: include your wizard session for correlation in Raindrop
+  context: {
+    properties: {
+      wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
+    },
+  },
+  selfDiagnostics: {
+    enabled: true,
+    // Optional: replace defaults with domain-specific categories
+    signals: {
+      payment_failed: {
+        description: 'Payment processing failed after retries.',
+        sentiment: 'NEGATIVE',
+      },
+    },
+    // Optional: extra guidance for the model
+    guidance: "Only report when the user's transaction is actually blocked.",
+  },
+});
+```
+
+You don't need to mention self diagnostics in your system prompt — the SDK
+handles the tool description automatically.
+
+When the agent calls the tool, a signal is tracked on the same `eventId`:
+
+```json
+{
+  "event_id": "evt_...",
+  "signal_name": "self diagnostics - missing_context",
+  "signal_type": "agent",
+  "properties": {
+    "source": "agent_reporting_tool",
+    "category": "missing_context",
+    "detail": "User asked to fix deployment but no access to logs or SSH credentials."
+  }
+}
+```
+
 ### Nested LLM Calls in Tools
 
 If your tool makes additional LLM calls, wrap them too for full trace
@@ -336,6 +391,7 @@ const summarizeTool = tool({
           wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
         },
       },
+      selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
       send: { events: false, traces: true },
     });
 
@@ -368,6 +424,7 @@ const { streamText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 const result = await streamText({
@@ -408,6 +465,7 @@ const { streamObject } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 const result = await streamObject({
@@ -466,7 +524,9 @@ const raindrop = createRaindropAISDK({
   writeKey: process.env.RAINDROP_WRITE_KEY!,
 });
 
-const wrapped = raindrop.wrap(ai);
+const wrapped = raindrop.wrap(ai, {
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
+});
 
 const weatherTool = ai.tool({
   description: 'Get current weather',
@@ -476,7 +536,7 @@ const weatherTool = ai.tool({
   },
 });
 
-const agent = new ToolLoopAgent({
+const agent = new wrapped.ToolLoopAgent({
   model: openai('gpt-4o'),
   tools: { weather: weatherTool },
   maxSteps: 5,
@@ -526,6 +586,7 @@ const { generateText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
 });
 
 const result = await generateText({
@@ -551,11 +612,13 @@ await raindrop.signals.track({
 
 ### Signal Types
 
-| Type         | Use Case                         |
-| ------------ | -------------------------------- |
-| `"default"`  | Generic signals (thumbs up/down) |
-| `"feedback"` | User comments about quality      |
-| `"edit"`     | User corrected the output        |
+| Type         | Use Case                                       |
+| ------------ | ---------------------------------------------- |
+| `"default"`  | Generic signals (thumbs up/down)               |
+| `"feedback"` | User comments about quality                    |
+| `"edit"`     | User corrected the output                      |
+| `"standard"` | Programmatic/custom instrumentation            |
+| `"agent"`    | Self diagnostics issues from `selfDiagnostics` |
 
 ```typescript
 // Thumbs up
@@ -620,6 +683,7 @@ const { generateText } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
   buildEvent: (messages) => {
     const userMessages = messages.filter((m) => m.role === 'user');
     const assistantMessages = messages.filter((m) => m.role === 'assistant');
@@ -758,6 +822,7 @@ const { generateText: innerGenerate } = raindrop.wrap(ai, {
       wizardSession: '__WIZARD_SESSION_UUID__', // REQUIRED
     },
   },
+  selfDiagnostics: { enabled: true }, // REQUIRED upgrade: unless the user explicitly requests they don't want this new feature
   send: { events: false, traces: true },
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raindrop-ai/wizard",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "homepage": "https://github.com/raindrop/wizard",
   "repository": "https://github.com/raindrop/wizard",
@@ -36,7 +36,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.50",
     "@inkkit/ink-markdown": "^1.0.0",
-    "@raindrop-ai/claude-agent-sdk": "^0.0.6",
+    "@raindrop-ai/claude-agent-sdk": "^0.0.7",
     "chalk": "^2.4.1",
     "clipboardy": "^4.0.0",
     "diff": "^8.0.3",