@raindrop-ai/deep-agents 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raindrop AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -97,7 +97,7 @@ The `createRaindropDeepAgents()` factory returns:
 - **Streaming**: Token-by-token streaming events are not captured individually; only the final aggregated response is tracked.
 - **Subagent isolation**: When using the `task` tool for subagent delegation, each subagent's callbacks fire independently.
 - **Concurrent invocations on a shared handler**: A single handler instance keeps one in-flight span map at a time. Running multiple `agent.invoke(...)` calls **concurrently with the same handler** (e.g. `Promise.all([agent.invoke(...), agent.invoke(...)])` with the same `raindrop.handler`) can scramble the linkage between events and traces. Instantiate one `createRaindropDeepAgents()` per concurrent request; sequential invocations on a shared handler are fully supported.
-- **Long chain inputs/outputs are truncated**: Chain-level `input` and `output` captured on the root event are truncated to ~8 KB to stay within the SDK's payload-size limit. Per-LLM child events still carry full prompts.
+- **Long chain inputs/outputs are truncated**: Chain-level `input` and `output` captured on the root event are truncated to ~8 KB to stay within the SDK's payload-size limit. Per-LLM child events still carry full prompts. Tool payloads are pruned to their cap _before_ JSON serialization, so a multi-MB tool output costs the cap — not the payload — on your event loop (truncated values carry a `...[truncated by raindrop]` marker).
 
 ## Testing
 

package/dist/index.d.mts

@@ -42,7 +42,6 @@ type SpanIds = {
     spanIdB64: string;
     parentSpanIdB64?: string;
 };
-
 type Attachment = {
     type: string;
     role: string;
@@ -86,6 +85,26 @@ type EventShipperOptions = {
     libraryName?: string;
     libraryVersion?: string;
     defaultEventName?: string;
+    /**
+     * Explicit Workshop / local debugger URL. Wins over env vars + auto-detect.
+     * Pass `null` to opt out of all mirroring (including auto-detect).
+     */
+    localDebuggerUrl?: string | null;
+    /**
+     * Optional project slug. When set, every outbound cloud request includes an
+     * `X-Raindrop-Project-Id: <projectId>` header. Empty / whitespace-only
+     * values are ignored. Slug format is validated on construction but never
+     * throws — the backend returns 400 on invalid values.
+     */
+    projectId?: string;
+    /**
+     * Per-field character cap applied to event input/output BEFORE buffering
+     * or serialization, so oversized payloads cost the cap — not the payload —
+     * on the calling code path. Truncated fields end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class EventShipper {
     private baseUrl;
@@ -96,14 +115,46 @@ declare class EventShipper {
     private sdkName;
     private prefix;
     private defaultEventName;
+    private projectId;
     private context;
     private buffers;
     private sticky;
     private timers;
     private inFlight;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    private hasShutdown;
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
+    private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
+    private requestHeaders;
+    /**
+     * Build the retry/timeout options for one POST, honoring the shutdown
+     * deadline. Returns `null` when the shutdown drain window is exhausted —
+     * the caller must drop the payload (with a rate-limited warning) instead
+     * of issuing a request that could outlive process exit.
+     *
+     * Checked fresh on EVERY send, so a shutdown that begins while the flush
+     * path is mid-drain takes effect immediately: no further retries, and the
+     * per-attempt timeout is clamped to the remaining window. After
+     * `shutdown()` returns (deadline cleared, `hasShutdown` still set),
+     * sends — late callers, or flush work the deadline abandoned mid-drain —
+     * run as a single short attempt rather than regaining the full retry
+     * schedule.
+     */
+    private requestOpts;
     patch(eventId: string, patch: Patch): Promise<void>;
     finish(eventId: string, patch: {
         output?: string;
@@ -115,8 +166,26 @@ declare class EventShipper {
     shutdown(): Promise<void>;
     trackSignal(signal: SignalInput): Promise<void>;
     identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    private warnShutdownDrop;
     private flushOne;
 }
+/**
+ * Hook fired per OTLP span right before the span is shipped (to the Raindrop
+ * API and to a local debugger). Lets callers inspect, rewrite, or drop the
+ * entire span — not just individual attributes — which is more flexible than
+ * an attribute-level hook (you can rename attributes, add new ones, drop the
+ * span outright, etc.).
+ *
+ * Return values:
+ *   - `undefined` or the same span: ship the span unchanged.
+ *   - a new `OtlpSpan`: ship the returned span in place of the original.
+ *   - `null`: drop the span entirely from every ship path.
+ *
+ * The hook runs on the hot path — keep it synchronous and side-effect-free.
+ * If the hook throws, the span is dropped (fail-closed) so a buggy hook can
+ * never accidentally ship raw, un-redacted spans.
+ */
+type TransformSpanHook = (span: OtlpSpan) => OtlpSpan | null | undefined;
 
 type InternalSpan = {
     ids: SpanIds;
@@ -137,6 +206,61 @@ type TraceShipperOptions = {
     sdkName?: string;
     serviceName?: string;
     serviceVersion?: string;
+    /**
+     * Explicit Workshop / local debugger URL. Wins over env vars + auto-detect.
+     * Pass `null` to opt out of all mirroring (including auto-detect).
+     */
+    localDebuggerUrl?: string | null;
+    /**
+     * Optional project slug. When set, every OTLP trace export includes an
+     * `X-Raindrop-Project-Id: <projectId>` header. Empty / whitespace-only
+     * values are ignored. Slug format is validated on construction but never
+     * throws — the backend returns 400 on invalid values.
+     */
+    projectId?: string;
+    /**
+     * Per-span hook that fires for every OTLP span right before the span is
+     * shipped (both to the Raindrop API and to a local debugger). Lets callers
+     * inspect, rewrite, or drop entire spans — rename attributes, add new ones,
+     * scrub additional secret-shaped values inside `ai.prompt.messages` /
+     * `ai.toolCall.args`, etc.
+     *
+     * Return values:
+     *   - `undefined` or the same span reference: ship the span unchanged.
+     *   - a new `OtlpSpan`: ship the returned span in place of the original.
+     *   - `null`: drop the span entirely from every ship path.
+     *
+     * The hook runs BEFORE the default redactor (which is the always-on floor
+     * for documented BYOK secrets). The default redactor still runs on the
+     * post-transform span unless `disableDefaultRedaction` is set, so even if
+     * a custom transform overlooks a secret-shaped attribute, the floor catches
+     * it.
+     *
+     * The hook runs on the hot path — keep it synchronous and side-effect-free.
+     * If the hook itself throws, the span is dropped (fail-closed) so a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    transformSpan?: TransformSpanHook;
+    /**
+     * Disable the built-in default span transformer (which scrubs documented
+     * secret-shaped properties — `apiKey`, `secretAccessKey`, `privateKey`,
+     * etc. — inside `ai.request.providerOptions` and
+     * `ai.response.providerMetadata`).
+     *
+     * Default: `false` (i.e. default redaction is on). Setting this to `true`
+     * disables the floor entirely; provide a custom `transformSpan` if you
+     * still want some redaction in that case.
+     */
+    disableDefaultRedaction?: boolean;
+    /**
+     * Per-attribute character cap applied to every span attribute string value
+     * right before the span enters a ship path, so a multi-MB prompt/tool
+     * payload can never make the batch `JSON.stringify` (which runs on the
+     * event loop) cost seconds. Truncated values end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class TraceShipper {
     private baseUrl;
@@ -151,14 +275,58 @@ declare class TraceShipper {
     private flushIntervalMs;
     private maxBatchSize;
     private maxQueueSize;
+    private projectId;
     private queue;
     private timer;
     private inFlight;
-    /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
+    private transformSpanHook;
+    private disableDefaultRedaction;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every batch POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    private hasShutdown;
     constructor(opts: TraceShipperOptions);
+    /**
+     * Cap every string attribute value on the span. O(#attributes) length
+     * checks; only oversized values pay a slice. Runs AFTER the redaction
+     * pipeline so the default secret-scrub still sees parseable JSON in
+     * `ai.request.providerOptions` / `ai.response.providerMetadata` (capping
+     * first could cut a JSON blob mid-way, fail the parse, and ship secrets
+     * in the surviving prefix).
+     *
+     * A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored
+     * for span content, matching the Python SDK and the OTel SDK convention.
+     */
+    private capSpanAttributes;
+    /**
+     * Apply the user `transformSpan` hook (if any) followed by the default
+     * redactor (unless disabled). Returns either the (possibly new) span to
+     * ship, or `null` to drop the span entirely.
+     *
+     * Ordering: user hook runs first so callers can rewrite the span freely
+     * (rename attrs, add new ones, scrub things the default doesn't know
+     * about). The default redactor then runs on whatever the user produced,
+     * acting as the always-on floor for documented BYOK secrets. If the user
+     * sets `disableDefaultRedaction: true`, the floor is skipped.
+     *
+     * Fail-closed: if the user hook throws, the span is dropped — a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    private redactSpan;
     isDebugEnabled(): boolean;
     private authHeaders;
+    private requestHeaders;
     startSpan(args: {
         name: string;
         parent?: {
@@ -170,6 +338,7 @@ declare class TraceShipper {
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
     }): InternalSpan;
+    private mirrorToLocalDebugger;
     endSpan(span: InternalSpan, extra?: {
         attributes?: InternalSpan["attributes"];
         error?: unknown;
@@ -190,6 +359,8 @@ declare class TraceShipper {
     }): void;
     enqueue(span: OtlpSpan): void;
     flush(): Promise<void>;
+    /** See EventShipper.requestOpts — same shutdown-budget semantics. */
+    private requestOpts;
     shutdown(): Promise<void>;
 }
 
@@ -274,6 +445,12 @@ interface DeepAgentsOptions {
     debug?: boolean;
     userId?: string;
     convoId?: string;
+    /**
+     * Optional Raindrop project slug. When set, every outbound cloud request
+     * carries an `X-Raindrop-Project-Id` header. Unset → no header (the project
+     * resolves to `default` server-side; byte-identical to prior behavior).
+     */
+    projectId?: string;
     traceChains?: boolean;
 }
 type RaindropDeepAgentsClient = {

package/dist/index.d.ts

@@ -42,7 +42,6 @@ type SpanIds = {
     spanIdB64: string;
     parentSpanIdB64?: string;
 };
-
 type Attachment = {
     type: string;
     role: string;
@@ -86,6 +85,26 @@ type EventShipperOptions = {
     libraryName?: string;
     libraryVersion?: string;
     defaultEventName?: string;
+    /**
+     * Explicit Workshop / local debugger URL. Wins over env vars + auto-detect.
+     * Pass `null` to opt out of all mirroring (including auto-detect).
+     */
+    localDebuggerUrl?: string | null;
+    /**
+     * Optional project slug. When set, every outbound cloud request includes an
+     * `X-Raindrop-Project-Id: <projectId>` header. Empty / whitespace-only
+     * values are ignored. Slug format is validated on construction but never
+     * throws — the backend returns 400 on invalid values.
+     */
+    projectId?: string;
+    /**
+     * Per-field character cap applied to event input/output BEFORE buffering
+     * or serialization, so oversized payloads cost the cap — not the payload —
+     * on the calling code path. Truncated fields end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class EventShipper {
     private baseUrl;
@@ -96,14 +115,46 @@ declare class EventShipper {
     private sdkName;
     private prefix;
     private defaultEventName;
+    private projectId;
     private context;
     private buffers;
     private sticky;
     private timers;
     private inFlight;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    private hasShutdown;
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
+    private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
+    private requestHeaders;
+    /**
+     * Build the retry/timeout options for one POST, honoring the shutdown
+     * deadline. Returns `null` when the shutdown drain window is exhausted —
+     * the caller must drop the payload (with a rate-limited warning) instead
+     * of issuing a request that could outlive process exit.
+     *
+     * Checked fresh on EVERY send, so a shutdown that begins while the flush
+     * path is mid-drain takes effect immediately: no further retries, and the
+     * per-attempt timeout is clamped to the remaining window. After
+     * `shutdown()` returns (deadline cleared, `hasShutdown` still set),
+     * sends — late callers, or flush work the deadline abandoned mid-drain —
+     * run as a single short attempt rather than regaining the full retry
+     * schedule.
+     */
+    private requestOpts;
     patch(eventId: string, patch: Patch): Promise<void>;
     finish(eventId: string, patch: {
         output?: string;
@@ -115,8 +166,26 @@ declare class EventShipper {
     shutdown(): Promise<void>;
     trackSignal(signal: SignalInput): Promise<void>;
     identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    private warnShutdownDrop;
     private flushOne;
 }
+/**
+ * Hook fired per OTLP span right before the span is shipped (to the Raindrop
+ * API and to a local debugger). Lets callers inspect, rewrite, or drop the
+ * entire span — not just individual attributes — which is more flexible than
+ * an attribute-level hook (you can rename attributes, add new ones, drop the
+ * span outright, etc.).
+ *
+ * Return values:
+ *   - `undefined` or the same span: ship the span unchanged.
+ *   - a new `OtlpSpan`: ship the returned span in place of the original.
+ *   - `null`: drop the span entirely from every ship path.
+ *
+ * The hook runs on the hot path — keep it synchronous and side-effect-free.
+ * If the hook throws, the span is dropped (fail-closed) so a buggy hook can
+ * never accidentally ship raw, un-redacted spans.
+ */
+type TransformSpanHook = (span: OtlpSpan) => OtlpSpan | null | undefined;
 
 type InternalSpan = {
     ids: SpanIds;
@@ -137,6 +206,61 @@ type TraceShipperOptions = {
     sdkName?: string;
     serviceName?: string;
     serviceVersion?: string;
+    /**
+     * Explicit Workshop / local debugger URL. Wins over env vars + auto-detect.
+     * Pass `null` to opt out of all mirroring (including auto-detect).
+     */
+    localDebuggerUrl?: string | null;
+    /**
+     * Optional project slug. When set, every OTLP trace export includes an
+     * `X-Raindrop-Project-Id: <projectId>` header. Empty / whitespace-only
+     * values are ignored. Slug format is validated on construction but never
+     * throws — the backend returns 400 on invalid values.
+     */
+    projectId?: string;
+    /**
+     * Per-span hook that fires for every OTLP span right before the span is
+     * shipped (both to the Raindrop API and to a local debugger). Lets callers
+     * inspect, rewrite, or drop entire spans — rename attributes, add new ones,
+     * scrub additional secret-shaped values inside `ai.prompt.messages` /
+     * `ai.toolCall.args`, etc.
+     *
+     * Return values:
+     *   - `undefined` or the same span reference: ship the span unchanged.
+     *   - a new `OtlpSpan`: ship the returned span in place of the original.
+     *   - `null`: drop the span entirely from every ship path.
+     *
+     * The hook runs BEFORE the default redactor (which is the always-on floor
+     * for documented BYOK secrets). The default redactor still runs on the
+     * post-transform span unless `disableDefaultRedaction` is set, so even if
+     * a custom transform overlooks a secret-shaped attribute, the floor catches
+     * it.
+     *
+     * The hook runs on the hot path — keep it synchronous and side-effect-free.
+     * If the hook itself throws, the span is dropped (fail-closed) so a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    transformSpan?: TransformSpanHook;
+    /**
+     * Disable the built-in default span transformer (which scrubs documented
+     * secret-shaped properties — `apiKey`, `secretAccessKey`, `privateKey`,
+     * etc. — inside `ai.request.providerOptions` and
+     * `ai.response.providerMetadata`).
+     *
+     * Default: `false` (i.e. default redaction is on). Setting this to `true`
+     * disables the floor entirely; provide a custom `transformSpan` if you
+     * still want some redaction in that case.
+     */
+    disableDefaultRedaction?: boolean;
+    /**
+     * Per-attribute character cap applied to every span attribute string value
+     * right before the span enters a ship path, so a multi-MB prompt/tool
+     * payload can never make the batch `JSON.stringify` (which runs on the
+     * event loop) cost seconds. Truncated values end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class TraceShipper {
     private baseUrl;
@@ -151,14 +275,58 @@ declare class TraceShipper {
     private flushIntervalMs;
     private maxBatchSize;
     private maxQueueSize;
+    private projectId;
     private queue;
     private timer;
     private inFlight;
-    /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
+    private transformSpanHook;
+    private disableDefaultRedaction;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every batch POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    private hasShutdown;
     constructor(opts: TraceShipperOptions);
+    /**
+     * Cap every string attribute value on the span. O(#attributes) length
+     * checks; only oversized values pay a slice. Runs AFTER the redaction
+     * pipeline so the default secret-scrub still sees parseable JSON in
+     * `ai.request.providerOptions` / `ai.response.providerMetadata` (capping
+     * first could cut a JSON blob mid-way, fail the parse, and ship secrets
+     * in the surviving prefix).
+     *
+     * A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored
+     * for span content, matching the Python SDK and the OTel SDK convention.
+     */
+    private capSpanAttributes;
+    /**
+     * Apply the user `transformSpan` hook (if any) followed by the default
+     * redactor (unless disabled). Returns either the (possibly new) span to
+     * ship, or `null` to drop the span entirely.
+     *
+     * Ordering: user hook runs first so callers can rewrite the span freely
+     * (rename attrs, add new ones, scrub things the default doesn't know
+     * about). The default redactor then runs on whatever the user produced,
+     * acting as the always-on floor for documented BYOK secrets. If the user
+     * sets `disableDefaultRedaction: true`, the floor is skipped.
+     *
+     * Fail-closed: if the user hook throws, the span is dropped — a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    private redactSpan;
     isDebugEnabled(): boolean;
     private authHeaders;
+    private requestHeaders;
     startSpan(args: {
         name: string;
         parent?: {
@@ -170,6 +338,7 @@ declare class TraceShipper {
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
     }): InternalSpan;
+    private mirrorToLocalDebugger;
     endSpan(span: InternalSpan, extra?: {
         attributes?: InternalSpan["attributes"];
         error?: unknown;
@@ -190,6 +359,8 @@ declare class TraceShipper {
     }): void;
     enqueue(span: OtlpSpan): void;
     flush(): Promise<void>;
+    /** See EventShipper.requestOpts — same shutdown-budget semantics. */
+    private requestOpts;
     shutdown(): Promise<void>;
 }
 
@@ -274,6 +445,12 @@ interface DeepAgentsOptions {
     debug?: boolean;
     userId?: string;
     convoId?: string;
+    /**
+     * Optional Raindrop project slug. When set, every outbound cloud request
+     * carries an `X-Raindrop-Project-Id` header. Unset → no header (the project
+     * resolves to `default` server-side; byte-identical to prior behavior).
+     */
+    projectId?: string;
     traceChains?: boolean;
 }
 type RaindropDeepAgentsClient = {