@raindrop-ai/ai-sdk 0.0.22 → 0.0.23

package/README.md

@@ -192,6 +192,135 @@ v7 additionally runs:
 - **E2E native telemetry** - Real AI SDK v7 with MSW-intercepted payloads
 - **Subagent nesting** - Span hierarchy for nested generateText inside tool execution
 
+## Manual Traces
+
+Create trace spans manually alongside (or instead of) auto-instrumented ones. Useful for custom operations, DSL command extraction, or building trace trees for custom agent loops.
+
+Spans share the same trace tree as auto-instrumented spans when you pass matching `eventId` values.
+
+All three methods are available on every entrypoint (`.`, `./workers`, `./browser`).
+
+### One-shot spans
+
+Use `createSpan` when the operation is already complete and you know the duration:
+
+```ts
+raindrop.traces.createSpan({
+  name: "SET theme=dark",
+  eventId: "evt_123",
+  operationId: "ai.toolCall", // appears as a tool call in the dashboard
+  input: "SET theme=dark",
+  output: "OK",
+  durationMs: 12,
+});
+
+// Failed span
+raindrop.traces.createSpan({
+  name: "SET layout=invalid",
+  eventId: "evt_123",
+  operationId: "ai.toolCall",
+  input: "SET layout=invalid",
+  error: "Invalid layout value",
+  durationMs: 8,
+});
+```
+
+### Lifecycle spans
+
+Use `startSpan` / `endSpan` to time an operation in real time:
+
+```ts
+const span = raindrop.traces.startSpan({
+  name: "database_query",
+  eventId: "evt_123",
+  operationId: "ai.toolCall",
+});
+
+try {
+  const result = await db.query("SELECT ...");
+  raindrop.traces.endSpan(span);
+} catch (err) {
+  raindrop.traces.endSpan(span, { error: err });
+}
+```
+
+### Nested spans
+
+Pass a span as `parent` to build a trace tree:
+
+```ts
+const eventId = "evt_456";
+
+const agentTurn = raindrop.traces.startSpan({ name: "agent_turn", eventId });
+
+const subagent = raindrop.traces.startSpan({
+  name: "search_subagent",
+  eventId,
+  parent: agentTurn,
+});
+
+raindrop.traces.createSpan({
+  name: "grep_search",
+  eventId,
+  parent: subagent,
+  operationId: "ai.toolCall",
+  input: { pattern: "execute" },
+  output: { matches: 12 },
+  durationMs: 120,
+});
+
+raindrop.traces.endSpan(subagent);
+raindrop.traces.endSpan(agentTurn);
+
+await raindrop.flush();
+```
+
+### Mixing with auto-instrumented spans
+
+Use the same `eventId` for both `wrap()` calls and manual spans — they appear in the same trace tree:
+
+```ts
+const eventId = crypto.randomUUID();
+const { generateText } = raindrop.wrap(ai, {
+  context: { userId: "user_123" },
+});
+
+await generateText({
+  model: openai("gpt-4o"),
+  prompt: "Analyze this data",
+  experimental_telemetry: {
+    isEnabled: true,
+    metadata: eventMetadata({ eventId }),
+  },
+});
+
+raindrop.traces.createSpan({
+  name: "post_processing",
+  eventId,
+  input: "raw",
+  output: "processed",
+  durationMs: 50,
+});
+
+await raindrop.flush();
+```
+
+### API reference
+
+| Method | Description |
+|--------|-------------|
+| `raindrop.traces.createSpan(args)` | One-shot span with known duration |
+| `raindrop.traces.startSpan(args)` | Start a span, returns a `TraceSpan` handle |
+| `raindrop.traces.endSpan(span, extra?)` | Close a span opened with `startSpan` |
+
+**`createSpan` args:** `name`, `eventId`, `operationId?`, `parent?`, `input?`, `output?`, `durationMs`, `error?`
+
+**`startSpan` args:** `name`, `eventId`, `operationId?`, `parent?`
+
+**`endSpan` extra:** `error?` (`Error | string`)
+
+Set `operationId: "ai.toolCall"` to make spans appear as tool calls in the Raindrop dashboard.
+
 ## Notes
 
 - Spans include `ai.telemetry.metadata.raindrop.eventId` for correlation, and **omit** `ai.telemetry.metadata.raindrop.userId` to prevent duplicate span→event creation server-side.

package/dist/{chunk-7NLWLLB4.mjs → chunk-VQZMQSBQ.mjs}

@@ -4007,7 +4007,7 @@ function extractNestedTokens(usage, key) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.22"};
+  version: "0.0.23"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;

package/dist/index.browser.js

@@ -832,7 +832,7 @@ async function* asyncGeneratorWithCurrent(span, gen) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.22"};
+  version: "0.0.23"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;

package/dist/index.browser.mjs

@@ -830,7 +830,7 @@ async function* asyncGeneratorWithCurrent(span, gen) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.22"};
+  version: "0.0.23"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;

package/dist/index.node.js

@@ -837,7 +837,7 @@ globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = async_hooks.AsyncLocalStorage;
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.22"};
+  version: "0.0.23"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;

package/dist/index.node.mjs

@@ -1,4 +1,4 @@
-export { RaindropTelemetryIntegration, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent } from './chunk-7NLWLLB4.mjs';
+export { RaindropTelemetryIntegration, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent } from './chunk-VQZMQSBQ.mjs';
 import { AsyncLocalStorage } from 'async_hooks';
 
 globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = AsyncLocalStorage;

package/dist/index.workers.js

@@ -837,7 +837,7 @@ globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = async_hooks.AsyncLocalStorage;
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.22"};
+  version: "0.0.23"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;

package/dist/index.workers.mjs

@@ -1,4 +1,4 @@
-export { RaindropTelemetryIntegration, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent } from './chunk-7NLWLLB4.mjs';
+export { RaindropTelemetryIntegration, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent } from './chunk-VQZMQSBQ.mjs';
 import { AsyncLocalStorage } from 'async_hooks';
 
 if (!globalThis.RAINDROP_ASYNC_LOCAL_STORAGE) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raindrop-ai/ai-sdk",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "Standalone Vercel AI SDK integration for Raindrop (events + OTLP/HTTP JSON traces, no OTEL runtime)",
   "main": "dist/index.node.js",
   "module": "dist/index.node.mjs",