@raindrop-ai/ai-sdk 0.2.0 → 0.3.0

package/dist/index.browser.d.mts

@@ -9,6 +9,196 @@ type FeatureFlags = string[] | Record<string, FeatureFlagValue>;
  */
 declare function normalizeFeatureFlags(input: FeatureFlags): Record<string, string>;
 
+/**
+ * Detached sub-agent hand-off contract (`raindrop.handoff.*`).
+ *
+ * A detached hand-off is a sub-agent that runs outside the caller's process and
+ * reports as its OWN Raindrop event with its OWN lifecycle, rather than as spans
+ * nested inside the caller's trace. It crosses both the OTel trace boundary and
+ * the Raindrop event boundary, so nothing implicit links the two — the link is
+ * carried explicitly on span attributes.
+ *
+ * This is deliberately distinct from a *continuation*, where the remote process
+ * joins the caller's event by reusing its `eventId`. Continuations need none of
+ * these attributes: event-id grouping already merges those traces.
+ *
+ * Written by the caller, on the exact dispatch span:
+ *   raindrop.handoff.mode         = "detached"
+ *   raindrop.handoff.childEventId = <the child's event id>
+ *   raindrop.handoff.name         = <sub-agent name>
+ *
+ * Written by the child, on every span it emits:
+ *   raindrop.handoff.parentEventId = <the caller's event id>
+ *   raindrop.handoff.parentSpanId  = <the dispatch span id, hex>
+ *   raindrop.handoff.name          = <sub-agent name>
+ *   raindrop.agent.role            = "subagent"
+ *   raindrop.handoff.terminal      = "cancelled", when that happened
+ *
+ * Status is NOT part of this contract. The child event owns its own lifecycle,
+ * so a status attribute written by the caller would be a second writer of a
+ * field the child already determines: the caller returned a job handle and moved
+ * on, so anything it wrote would be a guess that goes stale. Readers derive
+ * status from the child event itself. `cancelled` is the one exception, because
+ * a cancelled run is span-for-span identical to a finished one, and it is
+ * written BY THE CHILD on itself so the child stays the only writer.
+ *
+ * Every attribute name lives here and nowhere else, mirroring the reader on the
+ * Raindrop backend. Nothing downstream re-spells these strings.
+ */
+/** Bare attribute suffixes — the contract's canonical names. */
+declare const HANDOFF_ATTRIBUTE_SUFFIXES: {
+    readonly mode: "raindrop.handoff.mode";
+    readonly childEventId: "raindrop.handoff.childEventId";
+    readonly parentEventId: "raindrop.handoff.parentEventId";
+    readonly parentSpanId: "raindrop.handoff.parentSpanId";
+    readonly name: "raindrop.handoff.name";
+    readonly terminal: "raindrop.handoff.terminal";
+    readonly agentRole: "raindrop.agent.role";
+};
+/**
+ * The Vercel AI SDK nests user metadata, so the same logical field can land
+ * bare, under `ai.telemetry.metadata.`, or under `ai.settings.context.`. The
+ * backend reader tries all three; this list is the same one it uses, kept here
+ * so a test can assert that every key this SDK emits is a form that reader
+ * accepts.
+ */
+declare const HANDOFF_ATTRIBUTE_PREFIXES: readonly ["ai.telemetry.metadata.", "ai.settings.context.", ""];
+declare const DETACHED_MODE = "detached";
+declare const SUBAGENT_AGENT_ROLE = "subagent";
+declare const HANDOFF_TERMINAL_CANCELLED = "cancelled";
+declare const TOOL_EVENTS_ALLOW = "allow";
+/** The terminal marker as it appears on an event's `properties`. */
+declare const HANDOFF_TERMINAL_PROPERTY_KEY: "raindrop.handoff.terminal";
+/** What a caller records when it launches a detached sub-agent. */
+type DetachedDispatch = {
+    /** The child's event id, allocated by the caller BEFORE dispatching. */
+    childEventId: string;
+    /** Sub-agent name, so caller and child label the run identically. */
+    name?: string;
+};
+/** The reverse reference a detached child carries on its own spans. */
+type DetachedChildLink = {
+    /** The caller's event id. */
+    parentEventId: string;
+    /** The dispatch span id, hex-encoded as the backend stores span ids. */
+    parentSpanId?: string;
+    name?: string;
+};
+
+/**
+ * Portable trace-context carrier for cross-process sub-agents.
+ *
+ * `toHeaders()` / `fromHeaders()` mirror LangSmith's
+ * `RunTree.toHeaders()` / `tracing_context(parent=headers)` so migrating from
+ * LangSmith is a rename rather than a redesign.
+ *
+ * Two carriers are understood:
+ *
+ *   1. Native — `x-raindrop-handoff`, plus W3C `traceparent` and a `baggage` of
+ *      `raindrop-*` keys. The standard pair is what other readers understand;
+ *      the Raindrop header is what survives an instrumented caller, and wins
+ *      where they disagree. See {@link HANDOFF_HEADER}.
+ *   2. LangSmith — `langsmith-trace` (dotted order) plus LangSmith's `baggage`.
+ *      Accepted on READ so a service already propagating LangSmith headers links
+ *      correctly with no call-site change.
+ *
+ * ## 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
+ * accept carriers from services inside your own trust boundary — the same
+ * constraint LangSmith documents for distributed tracing. Never take a carrier
+ * off a public, unauthenticated request.
+ *
+ * Trace and span ids are hex here, as W3C `traceparent` and the Raindrop backend
+ * both represent them. Use `base64ToHex` when converting from the base64 ids
+ * used inside the trace shippers.
+ */
+type TraceCarrier = {
+    /** Hex trace id (32 chars for a W3C-conformant id). */
+    traceId: string;
+    /** Hex span id of the dispatching span (16 chars for a W3C-conformant id). */
+    spanId: string;
+    /** Event the child should join (continuation) or reference (detached). */
+    eventId: string;
+    /** Set only for a detached hand-off: the child's OWN event id. */
+    childEventId?: string;
+    /** Sub-agent name, carried so the child can label its own run identically. */
+    name?: string;
+    convoId?: string;
+    userId?: string;
+};
+/**
+ * Native carrier: `x-raindrop-handoff`, plus standard `traceparent` and
+ * `raindrop-*` baggage.
+ *
+ * Three headers, not two. The standard pair is what other readers understand,
+ * and `x-raindrop-handoff` is what survives a fully instrumented caller —
+ * instrumentation owns `traceparent` and the baggage propagator owns `baggage`,
+ * so neither is ours to rely on. See {@link HANDOFF_HEADER}.
+ *
+ * Send all of them. `fromHeaders` does not care whether they arrived as request
+ * headers or as fields of a queue payload.
+ *
+ * `baggage` is REPLACED, not merged: spreading this over a header bag that
+ * already carries baggage of its own drops those entries. Merge the two field
+ * lists when the caller propagates baggage.
+ *
+ * `traceparent` is emitted only for W3C-conformant ids. A carrier read back from
+ * a LangSmith dotted order holds UUIDs, and a UUID contains `-`, so spelling one
+ * into `00-<trace>-<span>-01` yields a header whose next reader takes UUID
+ * fragments for the ids. The Raindrop header and the baggage carry the whole
+ * carrier either way, so the link survives the omission and does not survive the
+ * corruption.
+ */
+declare function toHeaders(carrier: TraceCarrier): Record<string, string>;
+/**
+ * LangSmith-shaped carrier, for a fleet that is mid-migration and has services
+ * on both sides. Prefer {@link toHeaders} — both of its headers are W3C
+ * standards, so gateways and proxies pass them through untouched.
+ *
+ * `langsmith-trace` is a dotted order: segments of `<stamp>Z<run id>` from the
+ * trace root to the current run, and LangSmith packs metadata into `baggage`
+ * under `langsmith-metadata`. Two segments are emitted — the root run (whose id
+ * IS the trace id) and the dispatching run — because a single segment would say
+ * "this run is its own trace root" and collapse the two ids on read.
+ */
+declare function toLangSmithHeaders(carrier: TraceCarrier): Record<string, string>;
+/**
+ * A header container that answers by name rather than by property.
+ *
+ * A WHATWG `Headers` — what fetch, Next.js route handlers, Hono, Remix and
+ * Cloudflare Workers all call `request.headers` — keeps its fields in an
+ * internal slot, so `headers["baggage"]` is `undefined` and `Object.entries()`
+ * on one yields nothing. Next.js's `headers()` returns a `ReadonlyHeaders`,
+ * which is that object sealed behind a Proxy. `get()` is the only way in, and it
+ * is also where the spec puts case-insensitivity and the joining of repeated
+ * fields — so the container does that work rather than {@link readHeader}
+ * reimplementing it.
+ */
+type HeaderLookup = {
+    get(name: string): string | null | undefined;
+};
+type CarrierHeaders = Readonly<Record<string, string | string[] | undefined>> | HeaderLookup;
+/**
+ * Resume a parent context from either carrier.
+ *
+ * Returns `null` when no carrier is present. That is a legitimate state — the
+ * child was invoked directly rather than dispatched — not an error.
+ *
+ * Read the trust-boundary note at the top of this file before calling this on
+ * request headers.
+ */
+declare function fromHeaders(headers: CarrierHeaders): TraceCarrier | null;
+/**
+ * Allow the next {@link warnUnresolvedCarrier} to speak again.
+ *
+ * For tests: a once-per-process latch that no test can clear makes every
+ * assertion after the first depend on which test ran first, so a suite would
+ * pass purely because an earlier case consumed the one warning.
+ */
+declare function resetUnresolvedCarrierWarning(): void;
+
 type OtlpAnyValue = {
     stringValue?: string;
     intValue?: string;
@@ -509,6 +699,251 @@ declare class TraceShipper extends TraceShipper$1 {
     constructor(opts: ConstructorParameters<typeof TraceShipper$1>[0]);
 }
 
+/**
+ * Detached sub-agent hand-offs for the AI SDK integration.
+ *
+ * A detached sub-agent runs in another process (a queue worker, a container, a
+ * different machine) and does NOT block the caller. It reports as its own
+ * Raindrop event with its own lifecycle, so nothing implicit links the two —
+ * neither the OTel trace nor the event id survives the boundary. The link is
+ * carried explicitly: the caller stamps `raindrop.handoff.*` on the exact span
+ * that dispatched, the child stamps the reverse reference on every span it
+ * emits, and a carrier on the request/message body ties them together.
+ *
+ * The attribute names live in `@raindrop-ai/core`'s hand-off contract and are
+ * never re-spelled here.
+ *
+ * ## Trust boundary
+ *
+ * `resume()` reads a carrier that names the event the child will be attributed
+ * to, so accepting one from an untrusted caller lets that caller write into
+ * another tenant's trace. Only pass headers that came from inside your own trust
+ * boundary.
+ */
+
+/**
+ * Output recorded for a child that ended without producing an answer.
+ *
+ * An event is created only from a run that reported something, so "nothing" is
+ * the one outcome a child cannot leave implicit.
+ */
+declare const SUBAGENT_CANCELLED_OUTPUT = "Cancelled before producing a result.";
+declare const SUBAGENT_ABORTED_OUTPUT = "Aborted before producing a result.";
+/**
+ * The turn a launch is happening inside.
+ *
+ * Supplied by whatever holds spans open — the telemetry integration. Absent when
+ * a launch happens outside any instrumented generation (a plain queue producer),
+ * in which case the launch records its own dispatch span.
+ */
+type ActiveDispatch = {
+    /** The caller's event id. */
+    eventId: string;
+    userId?: string;
+    convoId?: string;
+    /**
+     * The model's own tool-call span — the exact span that dispatched. Present
+     * only while a tool's `execute` is running on the AI SDK v7 native-telemetry
+     * path, which is the only place the dispatching span is still open.
+     */
+    dispatchSpan?: InternalSpan;
+    /** The turn's still-open spans, which carry the tool-events opt-in. */
+    turnSpans: InternalSpan[];
+    /**
+     * The turn's input-capture setting (`experimental_telemetry.recordInputs`).
+     * A dispatch span synthesized inside this turn records its `input` only when
+     * the turn allows input capture — the same gate every other span of the turn
+     * applies to what the caller sends.
+     */
+    recordInputs?: boolean;
+};
+/** What the hand-off API needs from whatever holds spans open. */
+type HandoffSpanSource = {
+    activeDispatch(): ActiveDispatch | undefined;
+    /** Spans still open for a child's own event, for the terminal marker. */
+    openSpansForEvent(eventId: string): InternalSpan[];
+};
+type SubagentDispatchOptions = {
+    /** Sub-agent name. The child labels its own run with the same value. */
+    name?: string;
+    /**
+     * Name for the dispatch span, when this SDK has to synthesize one because no
+     * tool call was open. Defaults to `launch_subagent`. Dispatching from inside a
+     * tool's `execute` uses the model's own tool span, so this is ignored there.
+     */
+    toolName?: string;
+    /**
+     * Reuse an id the caller already has (a queue job id, say) instead of minting
+     * one. Either way the id is known BEFORE dispatch, which is what makes the
+     * link resolvable while the child is still queued.
+     */
+    childEventId?: string;
+    /** The caller's event id, when no instrumented turn is active to read it from. */
+    eventId?: string;
+    userId?: string;
+    convoId?: string;
+    /** Dispatch arguments, recorded on the dispatch span this call synthesizes. */
+    input?: unknown;
+};
+type SubagentDispatch = {
+    /** The child's event id. Send it with the job; the child reports under it. */
+    childEventId: string;
+    name?: string;
+    /** Headers to put on the dispatch. Empty when there was no caller context. */
+    headers: Record<string, string>;
+    /**
+     * The carrier behind {@link headers}, for transports that are not HTTP (a
+     * queue message body, a workflow input). `null` when no caller event id could
+     * be resolved, in which case the child still runs — it just has nothing to be
+     * attributed to.
+     */
+    carrier: TraceCarrier | null;
+};
+/**
+ * Fallbacks for a run with no carrier, i.e. a child invoked directly.
+ *
+ * These do NOT override a carrier. Every field here names something the caller
+ * already recorded on its dispatch span, so a local value winning would put the
+ * child somewhere the link does not reach: its own event id instead of the one
+ * the caller minted, or its own conversation instead of the supervisor's.
+ */
+type SubagentResumeOptions = {
+    /** Used when the carrier supplied no name. */
+    name?: string;
+    /** Used when the carrier supplied no child event id. */
+    eventId?: string;
+    userId?: string;
+    convoId?: string;
+};
+/** Metadata for a child's generations. Spread straight into `eventMetadata()`. */
+type SubagentRunMetadata = {
+    eventId: string;
+    userId?: string;
+    convoId?: string;
+    subagent?: DetachedChildLink;
+};
+type SubagentRun = {
+    /** The child's OWN event id, adopted from the carrier when it supplied one. */
+    eventId: string;
+    name?: string;
+    userId?: string;
+    convoId?: string;
+    /** The caller that dispatched this run, or `null` when invoked directly. */
+    parent: DetachedChildLink | null;
+    /** Pass to `eventMetadata()` on every generation this run makes. */
+    metadata: SubagentRunMetadata;
+    /**
+     * Report that the run was cancelled.
+     *
+     * A cancelled run is span-for-span identical to a finished one — spans close,
+     * nothing errors, there is just no answer — so it is the one outcome that
+     * needs stating explicitly. Written by the child on itself, never by the
+     * caller. The reason is recorded as the run's output, because a child that
+     * ends without output produces no event at all and leaves the caller unable
+     * to tell a failure from a job that never started.
+     */
+    cancel(reason?: string): Promise<void>;
+    /**
+     * Report that the run failed, recording `reason` as its output for the same
+     * reason {@link cancel} does. Use this when the failure happens outside a
+     * generation (the job died before reaching the model); a generation that
+     * throws already reports itself.
+     */
+    fail(reason: unknown): Promise<void>;
+};
+type SubagentApiOptions = {
+    traceShipper: TraceShipper;
+    eventShipper: EventShipper;
+    sendTraces: boolean;
+    sendEvents: boolean;
+    debug: boolean;
+    spanSource?: HandoffSpanSource;
+    defaultContext?: {
+        userId?: string;
+        convoId?: string;
+        eventId?: string;
+    };
+    /**
+     * Which child events have already reported an outcome, shared across every
+     * `SubagentApi` built from one client.
+     *
+     * A client exposes `subagents` and each telemetry integration owns another
+     * instance, but a child settles on one and finishes its generation on the
+     * other. Keeping this per-instance let the integration's finalizer overwrite
+     * an explicit `cancel()` with a generic finish, dropping the terminal marker
+     * and deriving `finished` for a run that was cancelled.
+     */
+    settledEventIds?: Set<string>;
+};
+declare class SubagentApi {
+    private readonly opts;
+    /**
+     * Child events whose outcome `cancel()` / `fail()` already reported, so the
+     * generation finalizer does not overwrite an explicit reason with a generic
+     * one when the run also ends through the AI SDK.
+     */
+    private readonly settledEventIds;
+    constructor(opts: SubagentApiOptions);
+    /** True when this child's outcome has already been reported. */
+    wasSettledExplicitly(eventId: string): boolean;
+    /**
+     * Record an outcome reported somewhere other than `cancel()` / `fail()`, so
+     * first-outcome-wins holds across every path that can state one.
+     *
+     * An aborted generation is such a path: an AbortSignal cancellation IS the
+     * run's outcome, and the `fail(err)` that a catch block around the aborted
+     * call naturally reports would otherwise error the child's spans — which is
+     * the only thing separating `failed` from `cancelled`.
+     */
+    noteSettled(eventId: string): void;
+    private remember;
+    /**
+     * Record a detached sub-agent on this turn: allocate the child's event id,
+     * stamp the dispatch, and return the headers to send with the job.
+     *
+     * This dispatches nothing — you do, moments later, with the returned headers.
+     * Nothing here waits for the child either, or claims to know how it is doing.
+     * Readers derive that from the child's own event.
+     */
+    subagent(options?: SubagentDispatchOptions): SubagentDispatch;
+    private recordLaunch;
+    /**
+     * Record a dispatch span for a launch with no open tool-call span to decorate:
+     * a launch from outside a tool's `execute`, or from a caller that is not an
+     * LLM turn at all (an HTTP handler that enqueues jobs). Shaped as a tool call
+     * so it reads identically to a model-issued launch.
+     */
+    private synthesizeDispatchSpan;
+    /**
+     * Adopt a carrier as the current run's parent reference.
+     *
+     * A missing carrier is a legitimate state — the child was invoked directly
+     * rather than dispatched — so this always returns a usable run and leaves
+     * `parent` null. Call sites stay unconditional.
+     */
+    resume(carrierOrHeaders: CarrierHeaders | TraceCarrier | null | undefined, options?: SubagentResumeOptions): SubagentRun;
+    /**
+     * A carrier arrives from outside this process, so a hostile or merely broken
+     * header bag must cost the job its link, never its run.
+     */
+    private readCarrier;
+    /**
+     * Mark a failed child's own spans as errored.
+     *
+     * Reporting the reason as output is what gets the child an event at all, but
+     * output alone is not enough: status is derived from span shape, and a child
+     * with final output and no error spans derives `finished`. A failed job
+     * reporting success is worse than one reporting nothing, so the failure has
+     * to land on the telemetry too, not just in the text.
+     *
+     * This is the child describing its own run, not a caller writing a status it
+     * cannot observe — the child's own spans are exactly where the contract puts
+     * failure.
+     */
+    private recordFailureOnSpans;
+    private settle;
+}
+
 /**
  * Raindrop telemetry integration for AI SDK v7+
  *
@@ -607,6 +1042,8 @@ type RaindropTelemetryIntegrationOptions = {
      */
     subagentWrapping?: boolean;
     debug?: boolean;
+    /** See {@link SubagentApiOptions.settledEventIds}. */
+    settledEventIds?: Set<string>;
     context?: {
         userId?: string;
         eventId?: string;
@@ -641,7 +1078,51 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
      * (the `event.callId` can be the same for parallel sibling tools).
      */
     private readonly priorParentContexts;
+    /**
+     * Detached sub-agent hand-offs: record a sub-agent that runs in another
+     * process and reports as its own event, or resume one here from a carrier.
+     *
+     * @see {@link SubagentApi}
+     */
+    readonly subagents: SubagentApi;
+    /**
+     * Record a detached sub-agent on the turn that is live right now.
+     *
+     * Returns the dispatch — the child's event id and the headers to send with
+     * the job. Dispatching is still yours to do; this only states that you are
+     * about to, so a reader can follow the link before the child exists.
+     */
+    subagent(options?: SubagentDispatchOptions): SubagentDispatch;
     constructor(opts: RaindropTelemetryIntegrationOptions);
+    /**
+     * The turn a `subagent()` dispatch is happening inside.
+     *
+     * Resolved from the parent-tool context first, which is the only way to reach
+     * the EXACT span that dispatched: the tool call the model itself issued, still
+     * open while its `execute` runs. Falling back to the event id lets a launch
+     * from elsewhere in the turn (a queue producer called mid-generation) still
+     * find the turn's spans, which is where the tool-events opt-in has to land.
+     */
+    private activeDispatch;
+    /** Spans still open for an event, so a late outcome can still be stated. */
+    private openSpansForEvent;
+    /**
+     * End-attributes that keep a detached child legible when it ends without an
+     * answer — an error, an abort, a cancellation.
+     *
+     * An event is created from an LLM span only when it has a finish reason and
+     * non-empty output, so a child that dies silently produces NO event, and the
+     * caller's hand-off pill stays on `queued` forever — indistinguishable from a
+     * job that never started. Reporting the abort reason as the run's output is
+     * what makes the outcome visible. Only detached children get this: an inline
+     * generation's failure is already legible from its caller's own event.
+     *
+     * And only the run's OUTERMOST generation gets it (see `nestedInEvent`): an
+     * inner sub-call ending badly is not the run ending, and since an event is
+     * created from an LLM span with output, `ai.response.text` here would state
+     * the run's outcome through the span while the turn is still working.
+     */
+    private abortOutcomeAttrs;
     /** Flush any buffered events and trace spans to their destinations. */
     flush: () => Promise<void>;
     /** Flush and stop the background flush timers. */
@@ -892,6 +1373,30 @@ type EventMetadataOptions = {
     properties?: Record<string, unknown>;
     /** Feature flags to attach to this event (merged with wrap-time flags; call-time wins) */
     featureFlags?: FeatureFlags;
+    /**
+     * Marks this generation as a DETACHED sub-agent's own run and references the
+     * caller that dispatched it. Pass `run.parent` from
+     * `subagents.resume(headers)`, or spread `run.metadata` in place of this whole
+     * options object.
+     *
+     * The reference is what links a child that shares neither trace nor event with
+     * its caller. It lands on every span the run emits, because spans are ingested
+     * and projected independently.
+     */
+    subagent?: DetachedChildLink;
+    /**
+     * Opt this turn in to producing an event even when its entire content is tool
+     * calls.
+     *
+     * A turn that only dispatches work finishes with
+     * `ai.response.finishReason = "tool-calls"` and no assistant text, and ingest
+     * drops such turns by default as intermediate steps. For a dispatch-only turn
+     * the tool calls ARE the content, so without this the caller's event is never
+     * created and a hand-off has nothing to attach to. `subagent()` sets it on
+     * the live turn; pass it here when the dispatch happens outside a turn this
+     * SDK instruments (the AI SDK v4-v6 `wrap()` path).
+     */
+    toolEvents?: typeof TOOL_EVENTS_ALLOW;
 };
 /**
  * Creates metadata for use with the AI SDK's `experimental_telemetry.metadata` option.
@@ -1311,6 +1816,32 @@ type RaindropAISDKClient = {
         context?: RaindropTelemetryIntegrationOptions["context"];
         subagentWrapping?: boolean;
     }): RaindropTelemetryIntegration;
+    /**
+     * Detached sub-agent hand-offs: record a sub-agent that runs in another
+     * process and reports as its own event, or resume one here from a carrier.
+     *
+     * On the AI SDK v7 native-telemetry path prefer
+     * `createTelemetryIntegration().subagents`. An integration knows which turn is
+     * live, so it can stamp the hand-off on the exact span the model dispatched
+     * from and put the tool-events opt-in on the caller's turn. This one records
+     * its own dispatch span instead, and the opt-in has to come from
+     * `eventMetadata({ toolEvents: "allow" })` on the caller's call.
+     *
+     * TRUST BOUNDARY: `resume()` reads a carrier that names the event the child
+     * will be attributed to. Only pass headers from inside your own trust
+     * boundary.
+     */
+    subagents: SubagentApi;
+    /**
+     * Record a detached sub-agent: allocate the child's event id, stamp the
+     * dispatch, and hand back the headers to send with the job.
+     *
+     * Named for what it records, not for an action it performs — dispatching the
+     * job stays yours. Mirrors `interaction.subagent()` in `raindrop-ai` and the
+     * Python SDK. On the v7 native-telemetry path prefer
+     * `createTelemetryIntegration().subagent()`, which knows which turn is live.
+     */
+    subagent(options?: SubagentDispatchOptions): SubagentDispatch;
     events: {
         patch(eventId: string, patch: EventPatch): Promise<void>;
         addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
@@ -1431,4 +1962,4 @@ type RaindropTelemetryOptions = RaindropAISDKOptions & {
  */
 declare function raindrop(options?: RaindropTelemetryOptions): RaindropTelemetryIntegration;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_MAX_TEXT_FIELD_CHARS, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type FeatureFlagValue, type FeatureFlags, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type RaindropTelemetryOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInput, type SelfDiagnosticsToolOptions, type SelfDiagnosticsToolResult, type StartSpanArgs, TRUNCATION_MARKER, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, boundedStringify, capText, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, normalizeFeatureFlags, raindrop, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };
+export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, type CarrierHeaders, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_MAX_TEXT_FIELD_CHARS, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, DETACHED_MODE, type DetachedChildLink, type DetachedDispatch, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type FeatureFlagValue, type FeatureFlags, HANDOFF_ATTRIBUTE_PREFIXES, HANDOFF_ATTRIBUTE_SUFFIXES, HANDOFF_TERMINAL_CANCELLED, HANDOFF_TERMINAL_PROPERTY_KEY, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type RaindropTelemetryOptions, SUBAGENT_ABORTED_OUTPUT, SUBAGENT_AGENT_ROLE, SUBAGENT_CANCELLED_OUTPUT, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInput, type SelfDiagnosticsToolOptions, type SelfDiagnosticsToolResult, type StartSpanArgs, SubagentApi, type SubagentDispatch, type SubagentDispatchOptions, type SubagentResumeOptions, type SubagentRun, type SubagentRunMetadata, TOOL_EVENTS_ALLOW, TRUNCATION_MARKER, type TraceCarrier, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, boundedStringify, capText, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, fromHeaders, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, normalizeFeatureFlags, raindrop, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, resetUnresolvedCarrierWarning, runWithParentToolContext, runWithRaindropCallMetadata, toHeaders, toLangSmithHeaders, withCurrent };