raindrop-ai 0.2.4 → 0.3.0

package/README.md

@@ -65,6 +65,141 @@ On runtimes that lack a usable `AsyncLocalStorage.enterWith` (notably Cloudflare
 - `withSpan`/`withTool` invoke your callback as `fn.apply(thisArg, args)` — the callback receives exactly the arguments you pass (an earlier version prepended a spurious leading `undefined`). If you had code compensating for that shifted argument, remove the workaround.
 - With per-client interaction registries, `resumeInteraction(eventId)` returns only interactions that **this** client began; a second client resuming the same event id gets its own fresh interaction rather than the first client's.
 
+## Detached sub-agents
+
+A **detached** sub-agent 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 context 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 supervisor = raindrop.begin({
+  eventId: turnId,
+  event: "supervisor_turn",
+  userId: "user_123",
+  convoId,
+  input: userMessage,
+});
+
+const dispatch = supervisor.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.
+await supervisor.finish({ output: `Dispatched researcher as job ${dispatch.childEventId}.` });
+```
+
+`subagent()` allocates `childEventId` **before** dispatching, so the
+caller's hand-off resolves while the job is still queued. It records a tool span
+carrying the hand-off stamps — named by your `toolName`, or `launch_subagent`
+when you pass none, so the span name is yours to choose rather than a name the
+SDK imposes. The sub-agent's own name travels on `raindrop.handoff.name`, which
+is where readers group by it. It returns
+`headers` (W3C `traceparent` + `raindrop-*` baggage + `x-raindrop-handoff`),
+`langsmithHeaders` for services that parse LangSmith's shape, and `carrier` for
+transports that are not HTTP.
+
+Send **all** of `headers`, not just `traceparent`. The standard pair is what other
+readers understand, but neither header is 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 a tenant id would strip every hand-off identity and leave the child
+unlinked. `x-raindrop-handoff` carries the same fields under a name no propagator
+owns; it is read last and wins. A carrier header arriving **repeated with
+differing values** is refused outright, leaving the child honestly unlinked rather
+than letting whoever prepended a value choose the event this process reports
+under.
+
+With tracing disabled there is no dispatch span for a carrier to reference, so
+`carrier` is `null` and both header bags are empty — rather than naming a span
+that was never recorded. `childEventId` is still allocated, so a caller that
+needs the child reporting under that id can pass it to the worker itself.
+
+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 = raindrop.resumeSubagent(message.headers);
+
+try {
+  const answer = await run.interaction.withTool({ name: "search_docs" }, () =>
+    search(message.task)
+  );
+  await run.finish({ output: answer });
+} catch (error) {
+  await run.fail(error);
+}
+```
+
+`run.interaction` is an ordinary interaction — `withSpan`, `withTool`, and
+`trackAiEvent` all work as usual. The reverse reference (`parentEventId`,
+`parentSpanId`, the sub-agent name, `agent.role=subagent`) is bound to the
+execution context for the life of the run, so **every** span the child emits
+carries it, including auto-instrumented LLM calls the SDK never sees. It is
+unbound when the run settles.
+
+`withSubagentRun` is the equivalent of Python's
+`with rd.resume_subagent(...) as run:` — it guarantees an outcome is reported
+even if the callback returns early or throws:
+
+```ts
+await raindrop.withSubagentRun(request.headers, async (run) => {
+  await run.finish({ output: await doTheWork() });
+});
+```
+
+### Endings
+
+- `run.finish({ output })` — the normal path, same shape as `interaction.finish`.
+- `run.fail(reason)` — errors the child's own span **and** reports the reason as
+  output. Both halves matter (see the ingest rules below). If the job died
+  before any span opened, one is recorded so there is something to mark.
+- `run.cancel(reason)` — writes `raindrop.handoff.terminal=cancelled` and
+  reports the reason as output. It deliberately does **not** error any span:
+  error spans are what separate failed from cancelled.
+
+### Two ingest rules worth knowing
+
+1. **A run with no output produces no event.** A child that dies silently leaves
+   its launcher on `queued` forever — indistinguishable from a job that never
+   started. That is why `fail()` and `cancel()` both write an output, and why
+   `withSubagentRun` closes an unsettled run rather than letting it evaporate.
+2. **Status is derived from the child's telemetry, not asserted.** A run with
+   final output and no errored span reads as *finished*, which is why `fail()`
+   must error a span and not merely say "failed" in the output. Correspondingly,
+   the dispatching turn is opted in to producing an event
+   (`raindrop.toolEvents=allow`), because a turn whose entire content is a
+   dispatch has no assistant text and is otherwise dropped as an intermediate
+   step.
+
+### Carrier precedence and the trust boundary
+
+The carrier wins over anything local. `resumeSubagent(headers, { convoId })`
+treats its options as fallbacks for the **no-carrier** case, not overrides:
+every field the carrier supplies names something the launcher 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.
+
+`resumeSubagent` returns a usable run even when there is no carrier — a
+sub-agent invoked directly rather than dispatched is a legitimate state, not an
+error — so call sites stay unconditional. A malformed carrier costs the link,
+never the request; check `run.linked` if you need to know.
+
+> **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.
+
+Carriers are also readable in LangSmith's `langsmith-trace` +
+`langsmith-metadata` shape, so a service already propagating those links with no
+call-site change.
+
 ## Payload size limits
 
 Text fields (ai input/output, tool span I/O, span content) are capped at