@raindrop-ai/eve 0.0.10 → 0.0.11

package/dist/index.d.mts

@@ -0,0 +1,455 @@
+import * as _vercel_otel from '@vercel/otel';
+import { RaindropAISDKClient } from '@raindrop-ai/ai-sdk';
+
+type HrTime = [number, number];
+type AttributeValue = string | number | boolean | Array<string | number | boolean | null | undefined> | null | undefined;
+interface Attributes {
+    [key: string]: AttributeValue;
+}
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags?: number;
+}
+interface InstrumentationScope {
+    name: string;
+    version?: string;
+    schemaUrl?: string;
+}
+interface Resource {
+    attributes: Attributes;
+}
+interface ReadableSpan {
+    readonly name: string;
+    readonly kind: number;
+    readonly startTime: HrTime;
+    readonly endTime: HrTime;
+    readonly status: {
+        code: number;
+        message?: string;
+    };
+    readonly attributes: Attributes;
+    readonly resource: Resource;
+    readonly instrumentationLibrary?: InstrumentationScope;
+    readonly instrumentationScope?: InstrumentationScope;
+    spanContext(): SpanContext;
+    readonly parentSpanId?: string;
+    readonly parentSpanContext?: SpanContext;
+}
+interface ExportResult {
+    code: number;
+    error?: Error;
+}
+interface RaindropEveExporterOptions {
+    /**
+     * Raindrop write key. Required to ship to Raindrop's hosted endpoint; when
+     * omitted, the exporter still mirrors to Workshop (when one is reachable).
+     */
+    writeKey?: string;
+    /**
+     * Raindrop API endpoint. Defaults to `https://api.raindrop.ai/v1/`.
+     * Trailing slash optional; `/traces` is always appended.
+     */
+    endpoint?: string;
+    /**
+     * Workshop / local debugger URL. Pass `false` to opt out entirely. Pass a
+     * URL string to force-enable. Leave undefined to use env vars +
+     * auto-detect (`RAINDROP_WORKSHOP`, `RAINDROP_LOCAL_DEBUGGER`, localhost in
+     * development).
+     */
+    localWorkshopUrl?: string | false;
+    /** Logical service name used as the OTel `service.name` resource attribute. */
+    serviceName?: string;
+    /** Service version (defaults to the eve SDK version). */
+    serviceVersion?: string;
+    /** SDK identifier used in log prefixes and User-Agent. */
+    sdkName?: string;
+    /**
+     * Optional Raindrop project slug. When set, every cloud trace export carries
+     * an `X-Raindrop-Project-Id` header. Empty / whitespace-only values are
+     * ignored. Unset → no header (byte-identical to prior behavior).
+     */
+    projectId?: string;
+    /** Print extra logs while exporting / mirroring. */
+    debug?: boolean;
+    /**
+     * Per-attribute character cap for exported string attribute values
+     * (truncated values end with `...[truncated by raindrop]`). Enforced
+     * before the OTLP batch is serialized so multi-MB prompt/completion
+     * attributes cost the cap — not the payload — and land truncated instead
+     * of being dropped at the ingest size limit. A stricter
+     * `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored.
+     * Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number;
+}
+/**
+ * SpanExporter implementation that posts spans to Raindrop's OTLP/HTTP JSON
+ * endpoint and (optionally) mirrors to a local Workshop daemon.
+ */
+declare class RaindropEveSpanExporter {
+    private readonly writeKey;
+    private readonly baseUrl;
+    private readonly localDebuggerUrl;
+    private serviceName;
+    private readonly serviceVersion;
+    private readonly sdkName;
+    private readonly projectId;
+    private readonly debug;
+    private readonly prefix;
+    private readonly maxTextFieldChars;
+    private inFlight;
+    private shuttingDown;
+    private auxShutdowns;
+    constructor(opts?: RaindropEveExporterOptions);
+    /** True when we have at least one destination (Raindrop or Workshop). */
+    hasDestinations(): boolean;
+    /**
+     * Update the OTLP `service.name` attribute. Called by Eve's
+     * `setup({ agentName })` so the resource attribute reflects the actual
+     * agent name when the caller didn't pin one via `opts.serviceName`.
+     */
+    setServiceName(serviceName: string): void;
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Register an extra teardown hook to run during {@link shutdown}. Used to
+     * drain the AI SDK trace + event shippers that the `@raindrop-ai/eve`
+     * integration builds alongside this exporter — without this, pending
+     * `track_partial` events and AI SDK trace spans would be dropped on
+     * SIGINT / SIGTERM.
+     */
+    attachAuxShutdown(fn: () => Promise<void>): void;
+}
+
+declare const RAINDROP_EVE_SDK_NAME: string;
+declare const RAINDROP_EVE_SDK_VERSION: string;
+/**
+ * Test-only: clear the per-session canonical turn-id cache between cases so a
+ * session id reused across tests doesn't inherit a previous test's turn id.
+ */
+declare function _resetCanonicalTurnIds(): void;
+/**
+ * Signature of `registerOTel` from `@vercel/otel`. Re-exported via the
+ * package's own type so consumers don't have to import the type themselves
+ * and we don't take a runtime dependency on the package.
+ */
+type RegisterOTelFn = typeof _vercel_otel.registerOTel;
+/**
+ * A single bag of author-supplied metadata, mirroring Eve 0.45's
+ * `InstrumentationMetadata` (`Readonly<Record<string, string>>`). Keys
+ * beginning with `eve.` are reserved by Eve and dropped if returned.
+ */
+type RaindropEveInstrumentationMetadata = Readonly<Record<string, string>>;
+/**
+ * The channel projection Eve exposes to instrumentation callbacks. `kind` is
+ * the channel identity Eve has for the current turn (`"http"`, `"schedule"`,
+ * `"subagent"`, `"unknown"`, or `channel:<name>` for authored channels);
+ * `metadata` is the channel's metadata snapshot (e.g. Slack `channelId` /
+ * `teamId` / `threadTs` / `triggeringUserId`).
+ *
+ * Typed structurally so `@raindrop-ai/eve` doesn't take a hard dependency on
+ * `eve`'s types (it's an optional peer). Cast `metadata` values
+ * to the concrete channel shape inside your callback when you need narrowing.
+ */
+interface RaindropEveInstrumentationChannel {
+    readonly kind: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+interface RaindropEveInstrumentationSession {
+    readonly auth: {
+        readonly current: unknown;
+        readonly initiator: unknown;
+    };
+    readonly id: string;
+    readonly parent?: unknown;
+}
+interface RaindropEveInstrumentationTurn {
+    readonly id: string;
+    readonly sequence: number;
+}
+interface RaindropEveInstrumentationStep {
+    readonly index: number;
+}
+interface RaindropEveInstrumentationModelInput {
+    readonly instructions: string | readonly unknown[] | undefined;
+    readonly messages: readonly unknown[];
+}
+/**
+ * Input passed to the `step.started` hook. Identical across Eve 0.45's
+ * `metadata["step.started"]` and Eve 0.53's `events["step.started"]`:
+ * `session.id` is the current session id and `turn` is top-level. The callback
+ * runs after Eve has built the final model input for a model-call attempt and
+ * before the AI SDK model call is constructed, so the returned values are
+ * inherited by every child span the AI SDK creates for that step.
+ */
+interface RaindropEveStepStartedMetadataInput {
+    readonly channel: RaindropEveInstrumentationChannel;
+    readonly modelInput: RaindropEveInstrumentationModelInput;
+    readonly session: RaindropEveInstrumentationSession;
+    readonly step: RaindropEveInstrumentationStep;
+    readonly turn: RaindropEveInstrumentationTurn;
+}
+/**
+ * Alias for the `events["step.started"]` input on Eve 0.53+. The shape is the
+ * same as {@link RaindropEveStepStartedMetadataInput}; only the config key
+ * (`events` vs `metadata`) and the result wrapper (`{ runtimeContext }` vs a
+ * flat record) changed between 0.45 and 0.53.
+ */
+type RaindropEveStepStartedEventInput = RaindropEveStepStartedMetadataInput;
+/**
+ * Eve 0.45–0.52's `InstrumentationMetadataConfig` — the callback-driven
+ * metadata hooks accepted by `defineInstrumentation`'s `metadata` field.
+ * Forwarded to Eve so the returned values land on AI SDK telemetry spans for
+ * the matching step. Superseded on Eve 0.53+ by
+ * {@link RaindropEveInstrumentationEventsConfig}; we emit both so a single
+ * definition works across the supported range.
+ */
+interface RaindropEveInstrumentationMetadataConfig {
+    /**
+     * Per-attempt metadata resolved before the model call so child spans
+     * created by the AI SDK inherit the returned values.
+     */
+    readonly "step.started"?: (input: RaindropEveStepStartedMetadataInput) => RaindropEveInstrumentationMetadata;
+}
+/**
+ * Result returned by the Eve 0.53+ `events["step.started"]` hook. The authored
+ * runtime context is merged into the AI SDK telemetry spans for the step. Keys
+ * beginning with `eve.` are reserved by Eve and dropped, so author `raindrop.*`
+ * keys only.
+ */
+interface RaindropEveStepStartedEventResult {
+    readonly runtimeContext: RaindropEveInstrumentationMetadata;
+}
+/**
+ * Eve 0.53+'s `InstrumentationEvents` — the callback-driven event hooks
+ * accepted by `defineInstrumentation`'s `events` field. The forward-looking
+ * shape consumers should prefer on Eve 0.53+. The callback returns
+ * `{ runtimeContext }` rather than the flat record the 0.45 `metadata` hook
+ * used.
+ */
+interface RaindropEveInstrumentationEventsConfig {
+    /**
+     * Per-attempt runtime context resolved before the model call so child spans
+     * created by the AI SDK inherit the returned values.
+     */
+    readonly "step.started"?: (input: RaindropEveStepStartedEventInput) => RaindropEveStepStartedEventResult | undefined;
+}
+/**
+ * Options for {@link defineRaindropInstrumentation}.
+ */
+interface RaindropEveInstrumentationOptions {
+    /**
+     * `registerOTel` from `@vercel/otel`. Pass the function directly so the
+     * SDK doesn't have to dynamically import a peer dep at runtime.
+     *
+     * Optional only because tests and advanced wiring may pre-register OTel
+     * elsewhere; in a normal Eve project you should always pass this.
+     */
+    registerOTel?: RegisterOTelFn;
+    /**
+     * Raindrop write key. Required to ship traces to Raindrop's hosted endpoint.
+     * When omitted, the integration still mirrors to Workshop if one is
+     * reachable — useful for local development without a hosted account.
+     *
+     * Falls back to `process.env.RAINDROP_WRITE_KEY` when undefined.
+     */
+    writeKey?: string;
+    /**
+     * Raindrop API endpoint. Defaults to `https://api.raindrop.ai/v1/`.
+     * Falls back to `process.env.RAINDROP_ENDPOINT` when undefined.
+     */
+    endpoint?: string;
+    /**
+     * Optional Raindrop project slug. When set, every outbound cloud request
+     * (trace exports and the AI SDK event/trace shippers) carries an
+     * `X-Raindrop-Project-Id` header. Unset → no header (the project resolves to
+     * `default` server-side; byte-identical to prior behavior). Falls back to
+     * `process.env.RAINDROP_PROJECT_ID` when undefined.
+     */
+    projectId?: string;
+    /**
+     * Workshop / local debugger URL.
+     *
+     *   - `string`     — force-enable mirroring to that URL.
+     *   - `false`      — opt out of mirroring entirely (no env vars, no auto-detect).
+     *   - `undefined`  — use the standard precedence: `RAINDROP_WORKSHOP` /
+     *     `RAINDROP_LOCAL_DEBUGGER` env vars, then auto-detect during local
+     *     development (localhost hostname or `NODE_ENV=development`).
+     */
+    localWorkshopUrl?: string | false;
+    /**
+     * OTel `service.name`. Defaults to the agent name resolved by Eve at compile
+     * time, so you rarely need to set this.
+     */
+    serviceName?: string;
+    /**
+     * Override the OTel `service.version` resource attribute.
+     */
+    serviceVersion?: string;
+    /**
+     * Forwarded to Eve: override the function identifier attached to AI SDK
+     * spans. Defaults to the agent name.
+     */
+    functionId?: string;
+    /**
+     * Eve 0.45 `InstrumentationMetadataConfig` — callback-driven metadata
+     * forwarded *verbatim* to Eve so the values it returns land on the AI SDK
+     * telemetry spans for the matching step. Use this for per-turn/per-step
+     * dynamic metadata sourced from the live request (e.g. Slack
+     * `channelId` / `teamId` / `threadTs` / `triggeringUserId` off
+     * `input.channel.metadata`):
+     *
+     * ```ts
+     * defineRaindropInstrumentation({
+     *   staticMetadata: { app: "demo-data-agent", team: "data" },
+     *   metadata: {
+     *     "step.started"(input) {
+     *       return {
+     *         "slack.channel_id": String(input.channel.metadata.channelId ?? ""),
+     *         "raindrop.userId": String(input.channel.metadata.triggeringUserId ?? ""),
+     *       };
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * The `step.started` callback is handed to Eve as instrumentation metadata
+     * and is **never** iterated as static authored metadata by this helper.
+     *
+     * For backwards compatibility a flat `Record<string, string>` is still
+     * accepted and treated exactly like {@link staticMetadata}; prefer
+     * `staticMetadata` for static values and reserve `metadata` for the Eve
+     * callback config.
+     */
+    metadata?: RaindropEveInstrumentationMetadataConfig | Record<string, string>;
+    /**
+     * Eve 0.53+ `events` config. The forward-looking equivalent of
+     * {@link metadata}'s `step.started` callback: the hook returns
+     * `{ runtimeContext }` instead of a flat record. Prefer this on Eve 0.53+.
+     *
+     * When both {@link events} and {@link metadata} supply a `step.started`
+     * hook, `events` wins. Whichever is provided is forwarded on BOTH the
+     * definition's `events` (read by Eve 0.53+) and `metadata` (read by Eve
+     * 0.45–0.52) fields, so a single config works across the supported range.
+     */
+    events?: RaindropEveInstrumentationEventsConfig;
+    /**
+     * Static Raindrop metadata merged onto every shipped Raindrop event /
+     * telemetry span. Unlike {@link metadata}'s `step.started` callback, these
+     * values are authored once and applied by the Raindrop helper itself
+     * (routed through `raindrop.properties` / `raindrop.*` control keys the
+     * same way the legacy flat `metadata` option was). Use this for stable
+     * attributes like `app` / `team` / `environment`.
+     */
+    staticMetadata?: Record<string, string>;
+    /**
+     * Default `userId` attached to every Raindrop event shipped from this
+     * agent. The integration won't emit a `track_partial` event unless it has
+     * a `userId`, so leave this populated if you want the run to show up in
+     * Workshop's Overview tab and in the Raindrop dashboard's event feed.
+     *
+     * When omitted, the SDK uses Eve's session id (`eve.session.id`) when it
+     * can resolve one per call, and falls back to the agent name otherwise.
+     */
+    userId?: string;
+    /**
+     * Default `eventName` for shipped events. Defaults to the AI SDK
+     * `operationId` (e.g. `"ai.streamText"`); usually you'd set this to
+     * something user-meaningful like `"agent.turn"`.
+     */
+    eventName?: string;
+    /**
+     * Forwarded to Eve: whether to record full model inputs in spans. Defaults
+     * to Eve's own default (`true` when instrumentation is configured).
+     */
+    recordInputs?: boolean;
+    /**
+     * Forwarded to Eve: whether to record full model outputs in spans. Defaults
+     * to Eve's own default (`true` when instrumentation is configured).
+     */
+    recordOutputs?: boolean;
+    /**
+     * Print extra logs while exporting / mirroring spans. Also enabled by
+     * `RAINDROP_AI_DEBUG=1` in the environment.
+     */
+    debug?: boolean;
+    /**
+     * Per-attribute character cap for exported string span attributes
+     * (truncated values end with `...[truncated by raindrop]`). Multi-MB
+     * prompt/completion attributes are capped before OTLP serialization so
+     * they cost the cap — not the payload — and land truncated instead of
+     * being dropped at the ingest size limit. A stricter
+     * `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored.
+     * Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number;
+}
+/**
+ * The shape returned by {@link defineRaindropInstrumentation}. It matches Eve's
+ * `InstrumentationDefinition` so it can be the default export of
+ * `agent/instrumentation.ts`.
+ */
+interface RaindropInstrumentationDefinition {
+    readonly functionId?: string;
+    /**
+     * Eve 0.45–0.52 reads the `step.started` hook from here. Always populated
+     * (the default hook pushes cross-sandbox sub-agent lineage) when running on
+     * those versions.
+     */
+    readonly metadata?: RaindropEveInstrumentationMetadataConfig;
+    /**
+     * Eve 0.53+ reads the `step.started` hook from here instead of `metadata`.
+     * Always populated; carries the same lineage + static + author metadata as
+     * `metadata`, just wrapped in `{ runtimeContext }`.
+     */
+    readonly events?: RaindropEveInstrumentationEventsConfig;
+    readonly recordInputs?: boolean;
+    readonly recordOutputs?: boolean;
+    readonly setup: (context: {
+        agentName: string;
+    }) => void;
+    /** The underlying exporter — exported for tests and advanced wiring. */
+    readonly exporter: RaindropEveSpanExporter;
+    /**
+     * The Raindrop AI SDK client backing this instrumentation. Use it from
+     * application / tool code to:
+     *   - `raindrop.users.identify(...)` to attach traits to the active user
+     *   - `raindrop.signals.track(...)` to record feedback / programmatic signals
+     *   - `raindrop.events.patch(...)` / `.finish(...)` / `.addAttachments(...)`
+     *     for fine-grained event updates
+     *   - `raindrop.traces.startSpan(...)` / `.createSpan(...)` for custom spans
+     *   - `raindrop.flush()` / `raindrop.shutdown()` for explicit lifecycle control
+     *
+     * `raindrop.shutdown()` is already wired into the OTel exporter's shutdown
+     * lifecycle, so most callers don't need to invoke it themselves.
+     */
+    readonly raindrop: RaindropAISDKClient;
+}
+/**
+ * Build a Raindrop-flavored Eve instrumentation definition.
+ *
+ * `agent/instrumentation.ts`:
+ *
+ * ```ts
+ * import { defineRaindropInstrumentation } from "@raindrop-ai/eve";
+ *
+ * export default defineRaindropInstrumentation({
+ *   writeKey: process.env.RAINDROP_WRITE_KEY,
+ *   staticMetadata: { team: "support" },
+ *   events: {
+ *     "step.started"(input) {
+ *       return {
+ *         runtimeContext: {
+ *           "slack.channel_id": String(input.channel.metadata.channelId ?? ""),
+ *         },
+ *       };
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineRaindropInstrumentation(opts?: RaindropEveInstrumentationOptions): RaindropInstrumentationDefinition;
+
+export { RAINDROP_EVE_SDK_NAME, RAINDROP_EVE_SDK_VERSION, type RaindropEveExporterOptions, type RaindropEveInstrumentationChannel, type RaindropEveInstrumentationEventsConfig, type RaindropEveInstrumentationMetadata, type RaindropEveInstrumentationMetadataConfig, type RaindropEveInstrumentationModelInput, type RaindropEveInstrumentationOptions, type RaindropEveInstrumentationSession, type RaindropEveInstrumentationStep, type RaindropEveInstrumentationTurn, RaindropEveSpanExporter, type RaindropEveStepStartedEventInput, type RaindropEveStepStartedEventResult, type RaindropEveStepStartedMetadataInput, type RaindropInstrumentationDefinition, type RegisterOTelFn, _resetCanonicalTurnIds, defineRaindropInstrumentation as default, defineRaindropInstrumentation };