@raindrop-ai/ai-sdk 0.2.0 → 0.3.0

package/README.md

@@ -190,6 +190,120 @@ Sub-agents (a `generateText`/`streamText` invoked from inside a tool's
 `execute`) nest automatically: the inner generation's spans are parented under
 the tool span so parent and child spans stay correctly nested.
 
+## Detached sub-agents
+
+A **detached** sub-agent is different: it runs in another process (a queue
+worker, a container, another machine), does not block its caller, and reports as
+its own Raindrop event with its own lifecycle. Neither the trace nor the event id
+survives that boundary, so the link is carried explicitly — the caller stamps it
+on the span it dispatched from, the child stamps the reverse reference on every
+span it emits, and a carrier travels with the job.
+
+**Caller** — allocate the child's event id and get the headers to send:
+
+```ts
+const rd = raindrop({ context: { userId: "user_123" } });
+registerTelemetry(rd);
+
+const launch_subagent = tool({
+  description: "Hand a task to a background sub-agent",
+  inputSchema: z.object({ task: z.string() }),
+  execute: async ({ task }) => {
+    const dispatch = rd.subagent({ name: "researcher", input: { task } });
+    await queue.send({ task, headers: dispatch.headers });
+    // Return a handle, not an answer — the answer is the child's to report.
+    return { jobId: dispatch.childEventId, status: "accepted" };
+  },
+});
+```
+
+The dispatch span is **your tool's span**, so it carries your tool's name — the
+example above emits `launch_subagent` because that is what the tool is called
+here, not because the SDK imposes it. `launch_subagent` is only the fallback
+name, used when `subagent()` has to synthesize a dispatch span because no tool
+call was open; pass `toolName` to choose your own. The sub-agent's own name
+travels on `raindrop.handoff.name` either way, which is where readers group by
+it.
+
+`subagent()` allocates `childEventId` **before** dispatching, so the caller's
+hand-off resolves while the job is still queued. It also opts the turn in to
+producing an event: a turn whose entire content is launches finishes with
+`finishReason: "tool-calls"` and no assistant text, and such turns are dropped as
+intermediate steps by default. If you launch from outside a turn this SDK
+instruments (the v4-v6 `wrap()` path), pass the opt-in yourself with
+`eventMetadata({ toolEvents: "allow" })`.
+
+The caller never writes the child's status. It returned a job handle and moved
+on; status is derived from the child's own event.
+
+**Child** — resume from the carrier and report under the id the caller allocated:
+
+```ts
+const run = rd.subagents.resume(dispatch.headers);
+
+try {
+  await generateText({
+    model: anthropic("claude-sonnet-4-5"),
+    prompt: job.task,
+    experimental_telemetry: { isEnabled: true, metadata: eventMetadata(run.metadata) },
+  });
+} catch (err) {
+  // Only needed for a failure OUTSIDE a generation — one that throws already
+  // reports itself.
+  await run.fail(err);
+}
+```
+
+`run.metadata` carries the child's event id, identity, and the reverse reference,
+which the integration stamps on every span the run emits. A cancellation is the
+one outcome telemetry cannot show on its own (spans close, nothing errors, there
+is just no answer), so state it with `run.cancel(reason)`; a generation cancelled
+via its `AbortSignal` is marked automatically.
+
+A child that ends without reporting anything produces no event at all, which
+leaves its caller unable to tell a failed job from one that never started. The
+SDK therefore records an abort reason as the run's output whenever a detached
+child errors, aborts, or is cancelled.
+
+Output alone is not enough for a failure, though. Status is derived from the
+child's telemetry — a run with final output and no errored span reads as
+`finished` — so `run.fail()` also marks the child's own spans as errored, and
+records one when the job died before it reached the model and left nothing to
+mark. `run.cancel()` deliberately does not: cancelled and failed are different
+states, and error spans are what separate them.
+
+`resume(headers)` returns a usable run even when there is no carrier — a child
+invoked directly rather than dispatched is a legitimate state, not an error — so
+call sites stay unconditional.
+
+The carrier wins over anything local. `resume(headers, { convoId })` treats its
+options as fallbacks for the no-carrier case, not overrides, because every field
+the carrier supplies names something the caller already recorded: a child that
+keeps its own convo id lands in a different conversation from the supervisor that
+launched it, and one that keeps its own event id leaves the caller's reference
+pointing at nothing.
+
+> **Trust boundary.** A carrier names the event a child will be attributed to, so
+> accepting one from an untrusted caller lets that caller write into another
+> tenant's trace. Only read carriers that came from inside your own trust
+> boundary.
+
+`fromHeaders` also accepts LangSmith's `langsmith-trace` + `langsmith-metadata`
+headers, so a service already propagating those links with no call-site change.
+
+**Send every header `dispatch.headers` gives you, not just `traceparent`.** There
+are three: the standard `traceparent` and `baggage` pair, which other readers
+understand, and `x-raindrop-handoff`, which carries the same fields under a name
+no propagator owns. The standard pair is not ours to rely on — an instrumented
+HTTP client rewrites `traceparent` from its own client span, and OTel's baggage
+propagator *replaces* `baggage` with the caller's own entries, so a caller
+propagating something ordinary like a tenant id would otherwise strip every
+hand-off identity and leave the child unlinked. The Raindrop header is read last
+and wins; the standard pair remains the fallback for a carrier written by a
+different sender. A carrier header that arrives **repeated with differing values**
+is refused entirely, leaving an honestly unlinked child rather than a guess about
+which value gets to name the event this process is attributed to.
+
 ### AI SDK v7+ native telemetry (advanced)
 
 For finer control you can build the integration from a `createRaindropAISDK`