raindrop-ai 0.2.4 → 0.3.0

package/dist/index.mjs

@@ -21,7 +21,7 @@ import {
   stringifyBounded,
   tracing,
   withRoutingContext
-} from "./chunk-XLEPN7ZO.mjs";
+} from "./chunk-5Y3LWBKV.mjs";
 import {
   __commonJS,
   __toESM
@@ -10304,6 +10304,65 @@ var Raindrop = class {
   resumeInteraction(eventId) {
     return this._tracing.getActiveInteraction(eventId);
   }
+  /**
+   * Opens the child's own event for a launched detached sub-agent.
+   *
+   * Sibling to {@link resumeInteraction}, and deliberately not the same thing:
+   * a resumed interaction JOINS the caller's event, while a detached sub-agent
+   * reports as its OWN event under the id the launcher minted, linked back only
+   * by the hand-off attributes both sides write. Every span the run emits
+   * carries the reverse reference until it reports a result.
+   *
+   * Pass the headers the request arrived with. A missing carrier is a
+   * legitimate state — the sub-agent was invoked directly rather than
+   * dispatched — so this always returns a usable run and leaves `parent` null;
+   * call sites stay unconditional. A malformed carrier costs the link, never
+   * the request.
+   *
+   * The carrier is authoritative for every identity field it supplies. The
+   * options are fallbacks for the direct-invocation case, not overrides: each
+   * field names something the launcher already recorded, so a locally minted
+   * value winning would strand the child outside the link.
+   *
+   * > **Trust boundary.** A carrier 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 read carriers that came from
+   * > inside your own trust boundary.
+   *
+   * @example
+   * ```typescript
+   * const run = raindrop.resumeSubagent(request.headers);
+   * try {
+   *   const answer = await doTheWork();
+   *   await run.finish({ output: answer });
+   * } catch (error) {
+   *   await run.fail(error);
+   * }
+   * ```
+   */
+  resumeSubagent(headers, options) {
+    return this._tracing.resumeSubagent(headers, options);
+  }
+  /**
+   * Runs `fn` as a detached sub-agent and guarantees the run reports an
+   * outcome, mirroring the Python SDK's `with rd.resume_subagent(...) as run:`.
+   *
+   * A run that returns without reporting output is closed with an abort reason,
+   * and one that throws is failed with it. That is not cosmetic: an event is
+   * created only from a run with non-empty output, so a child that dies
+   * silently produces no event at all and its launcher stays on `queued`
+   * forever — indistinguishable from a job that never started.
+   *
+   * @example
+   * ```typescript
+   * await raindrop.withSubagentRun(request.headers, async (run) => {
+   *   await run.finish({ output: await doTheWork() });
+   * });
+   * ```
+   */
+  withSubagentRun(headers, fn, options) {
+    return this._tracing.withSubagentRun(headers, fn, options);
+  }
   /**
    * Creates a framework-agnostic self-diagnostics tool definition.
    *

package/dist/tracing/index.d.mts

@@ -1,4 +1,4 @@
-import { Raindrop, RaindropSpanProcessor, PartialAiTrackEvent, Interaction, Tracer } from '../index.mjs';
+import { R as Raindrop, a as RaindropSpanProcessor, P as PartialAiTrackEvent, I as Interaction, C as CarrierHeaders, T as TraceCarrier, S as SubagentResumeOptions, b as SubagentRun, c as Tracer } from '../index-DBdUrUXc.mjs';
 import { Instrumentation } from '@opentelemetry/instrumentation';
 import * as traceloop from '@traceloop/node-server-sdk';
 import '@opentelemetry/api';
@@ -103,6 +103,8 @@ declare const tracing: (analytics: Raindrop, apiUrl: string, writeKey: string, o
      */
     createSpanProcessor(processorOptions?: traceloop.SpanProcessorOptions): RaindropSpanProcessor;
     begin(traceContext: PartialAiTrackEvent): Interaction;
+    resumeSubagent(carrierOrHeaders: CarrierHeaders | TraceCarrier | null | undefined, options?: SubagentResumeOptions): SubagentRun;
+    withSubagentRun<T>(carrierOrHeaders: CarrierHeaders | TraceCarrier | null | undefined, fn: (run: SubagentRun) => Promise<T> | T, options?: SubagentResumeOptions): Promise<T>;
     getActiveInteraction(eventId: string): Interaction;
     tracer(globalProperties?: Record<string, string>): Tracer;
     /**

package/dist/tracing/index.d.ts

@@ -1,4 +1,4 @@
-import { Raindrop, RaindropSpanProcessor, PartialAiTrackEvent, Interaction, Tracer } from '../index.js';
+import { R as Raindrop, a as RaindropSpanProcessor, P as PartialAiTrackEvent, I as Interaction, C as CarrierHeaders, T as TraceCarrier, S as SubagentResumeOptions, b as SubagentRun, c as Tracer } from '../index-DBdUrUXc.js';
 import { Instrumentation } from '@opentelemetry/instrumentation';
 import * as traceloop from '@traceloop/node-server-sdk';
 import '@opentelemetry/api';
@@ -103,6 +103,8 @@ declare const tracing: (analytics: Raindrop, apiUrl: string, writeKey: string, o
      */
     createSpanProcessor(processorOptions?: traceloop.SpanProcessorOptions): RaindropSpanProcessor;
     begin(traceContext: PartialAiTrackEvent): Interaction;
+    resumeSubagent(carrierOrHeaders: CarrierHeaders | TraceCarrier | null | undefined, options?: SubagentResumeOptions): SubagentRun;
+    withSubagentRun<T>(carrierOrHeaders: CarrierHeaders | TraceCarrier | null | undefined, fn: (run: SubagentRun) => Promise<T> | T, options?: SubagentResumeOptions): Promise<T>;
     getActiveInteraction(eventId: string): Interaction;
     tracer(globalProperties?: Record<string, string>): Tracer;
     /**