@raindrop-ai/openai-managed-agents 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,572 @@
+import OpenAI from 'openai';
+import { AgentSession, AgentSessionItem, AgentSessionInputParam, AgentSessionEvent } from 'openai/resources/beta/agents/agents';
+import { SessionCreateParamsBase } from 'openai/resources/beta/agents/sessions/sessions';
+import { Turn } from 'openai/resources/beta/agents/sessions/turns';
+
+type OtlpAnyValue = {
+    stringValue?: string;
+    intValue?: string;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values: OtlpAnyValue[];
+    };
+};
+type OtlpKeyValue = {
+    key: string;
+    value: OtlpAnyValue;
+};
+declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+type OtlpSpanStatus = {
+    code: (typeof SpanStatusCode)[keyof typeof SpanStatusCode] | number;
+    message?: string;
+};
+type OtlpSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: OtlpKeyValue[];
+    status?: OtlpSpanStatus;
+};
+type SpanIds = {
+    traceIdB64: string;
+    spanIdB64: string;
+    parentSpanIdB64?: string;
+};
+/** Kept structural so public integration declarations do not depend on private schemas. */
+type AppGitOptions = {
+    commitSha?: string | null;
+    commitDirty?: boolean | null;
+    branch?: string | null;
+    detectBranch?: boolean;
+    sourceDirectory?: string;
+    autoDetect?: boolean;
+};
+type AppGitSnapshot = Readonly<Record<string, unknown>>;
+type AppGitEnvironment = Readonly<Record<string, string | undefined>>;
+type AppGitLocalResult = {
+    commitSha?: string;
+    commitDirty?: boolean;
+    branch?: string;
+};
+type AppGitOperationOwner = string;
+type AppGitLocalResolver = (sourceDirectory: string | undefined, detectBranch: boolean, completed: (result: AppGitLocalResult) => void) => () => void;
+/** One client owns its defaults; operation snapshots never wait for discovery. */
+declare class AppGitContextImpl {
+    private defaults;
+    private explicit;
+    private explicitKeys;
+    private cancel;
+    private disposed;
+    private operations;
+    private operationOverflow;
+    private detectBranch;
+    private replayBranch;
+    private disabled;
+    constructor(options: AppGitOptions | false | undefined, runtime?: {
+        allowLocalGit?: boolean;
+        resolveLocal?: AppGitLocalResolver;
+        env?: AppGitEnvironment;
+        captureLegacyReplayBranch?: boolean;
+        allowDiscovery?: boolean;
+    });
+    private accept;
+    snapshot(properties?: Readonly<Record<string, unknown>>): AppGitSnapshot;
+    /** Safe defaults when no operation/span start was observed; never infer identity. */
+    snapshotExplicit(properties?: Readonly<Record<string, unknown>>, eventId?: string): AppGitSnapshot;
+    /** Existing replay branch reporting stays separate from opt-in event properties. */
+    snapshotForReplay(): AppGitSnapshot;
+    /** Merge a frozen span snapshot without losing client-authored provenance. */
+    mergeSnapshot(base: AppGitSnapshot, properties?: Readonly<Record<string, unknown>>, explicitKeys?: ReadonlySet<string>): AppGitSnapshot;
+    /** Shippers belonging to one client share this bounded operation registry. */
+    forOperation(eventId: string | undefined, properties?: Readonly<Record<string, unknown>>, owner?: AppGitOperationOwner): AppGitSnapshot;
+    releaseOperation(eventId: string, owner: AppGitOperationOwner): void;
+    finishOperation(eventId: string): void;
+    dispose(): void;
+}
+/** Structural at package boundaries: public SDK bundles contain independent copies of core. */
+type AppGitContext = Pick<AppGitContextImpl, "snapshot" | "snapshotForReplay" | "forOperation" | "finishOperation" | "dispose"> & {
+    snapshotExplicit?: AppGitContextImpl["snapshotExplicit"];
+    mergeSnapshot?: AppGitContextImpl["mergeSnapshot"];
+    releaseOperation?: (eventId: string, owner: AppGitOperationOwner) => void;
+};
+declare const AppGitContext: typeof AppGitContextImpl;
+type Attachment = {
+    type: string;
+    role: string;
+    name?: string;
+    value: string;
+};
+type IdentifyInput = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+type EventUsage = {
+    promptTokens?: number;
+    completionTokens?: number;
+};
+type Patch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    usage?: EventUsage;
+    error?: unknown;
+    properties?: Record<string, unknown>;
+    featureFlags?: Record<string, string>;
+    attachments?: Attachment[];
+    isPending?: boolean;
+    timestamp?: string;
+};
+type SignalInput = {
+    eventId: string;
+    name: string;
+    type?: "default" | "feedback" | "edit" | "standard" | "agent" | "agent_internal";
+    sentiment?: "POSITIVE" | "NEGATIVE";
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+    attachmentId?: string;
+    comment?: string;
+    after?: string;
+};
+type EventShipperOptions = {
+    appGit?: AppGitOptions | false;
+    /** Share with the trace shipper so one operation uses one source snapshot. */
+    appGitContext?: AppGitContext;
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    partialFlushMs?: number;
+    sdkName?: string;
+    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 appGitContext;
+    private ownsAppGitContext;
+    private readonly appGitOwner;
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private partialFlushMs;
+    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);
+    protected ownAppGitContextForShutdown(): void;
+    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: Pick<Patch, "output" | "model" | "usage" | "error" | "properties" | "featureFlags" | "userId">): Promise<void>;
+    flush(): Promise<void>;
+    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;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: Array<OtlpKeyValue | undefined>;
+};
+type TraceShipperOptions = {
+    appGit?: AppGitOptions | false;
+    appGitContext?: AppGitContext;
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    debugSpans?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    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 appGitContext;
+    protected ownsAppGitContext: boolean;
+    private readonly appGitOwner;
+    private appGitEventIds;
+    private appGitActiveSpans;
+    private appGitCaptured;
+    private appGitAdded;
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private debugSpans;
+    private sdkName;
+    private prefix;
+    private serviceName;
+    private serviceVersion;
+    private flushIntervalMs;
+    private maxBatchSize;
+    private maxQueueSize;
+    private projectId;
+    private queue;
+    private timer;
+    private inFlight;
+    /** 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?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
+        operationId?: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        startTimeUnixNano?: string;
+    }): InternalSpan;
+    private mirrorToLocalDebugger;
+    endSpan(span: InternalSpan, extra?: {
+        attributes?: InternalSpan["attributes"];
+        error?: unknown;
+        status?: OtlpSpanStatus;
+        endTimeUnixNano?: string;
+    }): void;
+    createSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
+        startTimeUnixNano: string;
+        endTimeUnixNano: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        status?: OtlpSpanStatus;
+    }): void;
+    enqueue(span: OtlpSpan): void;
+    flush(): Promise<void>;
+    /** See EventShipper.requestOpts — same shutdown-budget semantics. */
+    private requestOpts;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Run telemetry egress with OpenTelemetry tracing suppressed.
+ *
+ * Why this exists
+ * ---------------
+ * Raindrop integrations ship spans/events over HTTP with the global `fetch`
+ * (see {@link ../http.ts `postJson`}). When the host app also runs an OTel
+ * fetch/undici instrumentation — e.g. `@vercel/otel`'s `registerOTel`, which
+ * every Eve agent installs — that instrumentation wraps *our own* telemetry
+ * POSTs in a `fetch POST <endpoint>` span. Those spans are then handed to the
+ * very exporter that issued the request, so they get shipped right back to
+ * Raindrop and Workshop as standalone "runs" (and, because each export issues
+ * another fetch, they feed back on themselves). The result is a run list
+ * flooded with `fetch POST .../v1/traces`, `.../events/track_partial` and
+ * `.../live` entries that drown out the real agent turns — especially with
+ * sub-agents, where every sandbox runs its own instrumentation.
+ *
+ * The OTel-blessed fix is to mark the active context as "tracing suppressed"
+ * around the request; instrumentations check `isTracingSuppressed` and return
+ * a no-op span instead of recording one. We do this through a hook stashed on
+ * `globalThis` by the Node entrypoint ({@link ../index.node.ts}) so that:
+ *   - `@opentelemetry/api` / `@opentelemetry/core` stay *optional* — core never
+ *     hard-depends on them, and the hook is simply absent when they (and thus
+ *     any instrumentation to suppress) are not installed; and
+ *   - the browser bundle never pulls in `node:module`, mirroring how core
+ *     injects `AsyncLocalStorage` via `RAINDROP_ASYNC_LOCAL_STORAGE`.
+ *
+ * When no hook is present the callback runs unchanged, so suppression is a
+ * best-effort no-op rather than a hard requirement.
+ */
+/** Hook signature: run `fn` with OTel tracing suppressed, returning its value. */
+type SuppressTracingHook = <T>(fn: () => T) => T;
+declare global {
+    var RAINDROP_SUPPRESS_TRACING: SuppressTracingHook | undefined;
+}
+
+type ParentSpanContext = {
+    traceIdB64: string;
+    spanIdB64: string;
+    eventId: string;
+};
+interface ContextSpan {
+    readonly traceIdB64: string;
+    readonly spanIdB64: string;
+    readonly eventId: string;
+    log?(data: Record<string, unknown>): void;
+}
+interface AsyncLocalStorageLike<T> {
+    getStore(): T | undefined;
+    run<R>(store: T, callback: () => R): R;
+    enterWith?(store: T): void;
+}
+declare abstract class ContextManager {
+    abstract getParentSpanIds(): ParentSpanContext | undefined;
+    abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
+    abstract getCurrentSpan(): ContextSpan | undefined;
+    abstract isReady(): boolean;
+}
+declare global {
+    var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
+    var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
+}
+
+type SessionContext = {
+    [Key in keyof Pick<Patch, "userId" | "convoId" | "eventName" | "properties">]?: Patch[Key] | undefined;
+};
+type OpenAIManagedAgentsOptions = SessionContext & {
+    writeKey?: string | undefined;
+    endpoint?: string | undefined;
+    projectId?: string | undefined;
+    debug?: boolean | undefined;
+    appGit?: AppGitOptions | false | undefined;
+    localWorkshopUrl?: string | false | undefined;
+    maxTextFieldChars?: number | undefined;
+    /** Custom event identity for hosts that namespace their telemetry. */
+    eventId?: ((turnId: string) => string) | undefined;
+    /** Applied to captured text, tool payloads, and errors before shipping. */
+    redact?: ((text: string) => string) | undefined;
+};
+
+declare class RaindropManagedAgentsHandler {
+    private events;
+    private traces;
+    private opts;
+    private sessions;
+    private idleSessions;
+    private completed;
+    constructor(events: EventShipper, traces: TraceShipper, opts: OpenAIManagedAgentsOptions);
+    private text;
+    private setAttributes;
+    private sessionCapture;
+    private cacheSession;
+    onSession(session: AgentSession, context?: SessionContext): void;
+    onInput(sessionId: string, input: SessionCreateParamsBase["input"]): void;
+    private capture;
+    onTurn(turn: Turn): void;
+    onItem(sessionId: string, item: AgentSessionItem): void;
+    onInputEvents(sessionId: string, events: AgentSessionInputParam[]): void;
+    onEvent(event: AgentSessionEvent): void;
+    private complete;
+    closeSessionTurns(sessionId: string, error?: Error): void;
+    forgetSession(sessionId: string, error?: Error): void;
+    shutdown(): void;
+}
+
+type RaindropOpenAIManagedAgentsClient = {
+    handler: RaindropManagedAgentsHandler;
+    wrap(client: OpenAI, context?: SessionContext): OpenAI;
+    events: {
+        patch(eventId: string, patch: Patch): Promise<void>;
+        finish(eventId: string, patch: Pick<Patch, "output" | "model" | "properties">): Promise<void>;
+        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+        setProperties(eventId: string, properties: NonNullable<Patch["properties"]>): Promise<void>;
+    };
+    users: {
+        identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    };
+    signals: {
+        track(signal: SignalInput): Promise<void>;
+    };
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+declare function createRaindropOpenAIManagedAgents(opts?: OpenAIManagedAgentsOptions): RaindropOpenAIManagedAgentsClient;
+
+export { type OpenAIManagedAgentsOptions, RaindropManagedAgentsHandler, type RaindropOpenAIManagedAgentsClient, type SessionContext, createRaindropOpenAIManagedAgents };