@raindrop-ai/pi-agent 0.0.2

package/dist/index.d-npTVS9Mf.d.cts

@@ -0,0 +1,216 @@
+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;
+};
+
+type Attachment = {
+    type: string;
+    role: string;
+    name?: string;
+    value: string;
+};
+type IdentifyInput = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+type Patch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    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 = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    partialFlushMs?: number;
+    sdkName?: string;
+    libraryName?: string;
+    libraryVersion?: string;
+    defaultEventName?: string;
+};
+declare class EventShipper {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private partialFlushMs;
+    private sdkName;
+    private prefix;
+    private defaultEventName;
+    private context;
+    private buffers;
+    private sticky;
+    private timers;
+    private inFlight;
+    constructor(opts: EventShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    patch(eventId: string, patch: Patch): Promise<void>;
+    finish(eventId: string, patch: {
+        output?: string;
+        model?: string;
+        properties?: Record<string, unknown>;
+        userId?: string;
+    }): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    trackSignal(signal: SignalInput): Promise<void>;
+    identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    private flushOne;
+}
+
+type InternalSpan = {
+    ids: SpanIds;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: Array<OtlpKeyValue | undefined>;
+};
+type TraceShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    debugSpans?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    sdkName?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+};
+declare class TraceShipper {
+    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 queue;
+    private timer;
+    private inFlight;
+    /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
+    private localDebuggerUrl;
+    constructor(opts: TraceShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    startSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        operationId?: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        startTimeUnixNano?: string;
+    }): InternalSpan;
+    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;
+        startTimeUnixNano: string;
+        endTimeUnixNano: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        status?: OtlpSpanStatus;
+    }): void;
+    enqueue(span: OtlpSpan): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+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;
+}
+
+export { type Attachment as A, EventShipper as E, type OtlpSpan as O, TraceShipper as T };

package/dist/index.d-npTVS9Mf.d.ts

@@ -0,0 +1,216 @@
+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;
+};
+
+type Attachment = {
+    type: string;
+    role: string;
+    name?: string;
+    value: string;
+};
+type IdentifyInput = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+type Patch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    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 = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    partialFlushMs?: number;
+    sdkName?: string;
+    libraryName?: string;
+    libraryVersion?: string;
+    defaultEventName?: string;
+};
+declare class EventShipper {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private partialFlushMs;
+    private sdkName;
+    private prefix;
+    private defaultEventName;
+    private context;
+    private buffers;
+    private sticky;
+    private timers;
+    private inFlight;
+    constructor(opts: EventShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    patch(eventId: string, patch: Patch): Promise<void>;
+    finish(eventId: string, patch: {
+        output?: string;
+        model?: string;
+        properties?: Record<string, unknown>;
+        userId?: string;
+    }): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    trackSignal(signal: SignalInput): Promise<void>;
+    identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    private flushOne;
+}
+
+type InternalSpan = {
+    ids: SpanIds;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: Array<OtlpKeyValue | undefined>;
+};
+type TraceShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    debugSpans?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    sdkName?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+};
+declare class TraceShipper {
+    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 queue;
+    private timer;
+    private inFlight;
+    /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
+    private localDebuggerUrl;
+    constructor(opts: TraceShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    startSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        operationId?: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        startTimeUnixNano?: string;
+    }): InternalSpan;
+    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;
+        startTimeUnixNano: string;
+        endTimeUnixNano: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        status?: OtlpSpanStatus;
+    }): void;
+    enqueue(span: OtlpSpan): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+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;
+}
+
+export { type Attachment as A, EventShipper as E, type OtlpSpan as O, TraceShipper as T };

package/dist/index.d.cts

@@ -0,0 +1,138 @@
+import { Agent } from '@mariozechner/pi-agent-core';
+import { A as Attachment } from './index.d-npTVS9Mf.cjs';
+
+/**
+ * Options for the Raindrop Pi Agent client.
+ */
+interface RaindropPiAgentOptions {
+    /**
+     * Write key for direct authentication.
+     * Optional — when omitted, telemetry shipping is disabled with a warning.
+     */
+    writeKey?: string;
+    /** API endpoint URL (defaults to production) */
+    endpoint?: string;
+    /** Default user ID for all events */
+    userId?: string;
+    /** Default conversation ID to group related events */
+    convoId?: string;
+    /** Default event name (default: "pi_agent_prompt") */
+    eventName?: string;
+    /** Default properties attached to every event */
+    properties?: Record<string, unknown>;
+    /** Trace shipping configuration */
+    traces?: {
+        /** Enable trace shipping (default: true) */
+        enabled?: boolean;
+        /** Flush interval in milliseconds */
+        flushIntervalMs?: number;
+        /** Maximum batch size */
+        maxBatchSize?: number;
+        /** Maximum queue size */
+        maxQueueSize?: number;
+        /** Enable debug logging */
+        debug?: boolean;
+        /** Enable detailed span logging */
+        debugSpans?: boolean;
+    };
+    /** Event shipping configuration */
+    events?: {
+        /** Enable event shipping (default: true) */
+        enabled?: boolean;
+        /** Partial flush interval in milliseconds */
+        partialFlushMs?: number;
+        /** Enable debug logging */
+        debug?: boolean;
+    };
+}
+/**
+ * Per-subscribe overrides for context.
+ */
+interface PiAgentSubscribeOptions {
+    /** User ID override for this subscription */
+    userId?: string;
+    /** Conversation ID override */
+    convoId?: string;
+    /** Event name override */
+    eventName?: string;
+    /** Additional properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * The Raindrop Pi Agent client.
+ * Exposes the full API surface: subscribe, events, users, signals, flush, shutdown.
+ */
+interface RaindropPiAgentClient {
+    /**
+     * Subscribe to a Pi Agent instance for automatic telemetry.
+     * Returns an unsubscribe function.
+     *
+     * @param agent - The Pi Agent instance to observe
+     * @param options - Optional per-subscription overrides
+     * @returns Unsubscribe function to stop tracking
+     */
+    subscribe(agent: Agent, options?: PiAgentSubscribeOptions): () => void;
+    /** Event management methods */
+    events: {
+        /** Patch an existing event with additional data */
+        patch(eventId: string, data: Record<string, unknown>): Promise<void>;
+        /** Add attachments to an event */
+        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+        /** Set properties on an event */
+        setProperties(eventId: string, properties: Record<string, unknown>): Promise<void>;
+        /** Finish an event (trigger immediate shipping) */
+        finish(eventId: string): Promise<void>;
+    };
+    /** User identification methods */
+    users: {
+        /** Identify a user with traits */
+        identify(params: {
+            userId: string;
+            traits?: Record<string, unknown>;
+        }): Promise<void>;
+    };
+    /** Signal tracking methods */
+    signals: {
+        /** Track a signal (feedback, user action, etc.) */
+        track(params: {
+            eventId?: string;
+            name: string;
+            type?: "default" | "feedback" | "edit";
+            sentiment?: "POSITIVE" | "NEGATIVE";
+            timestamp?: string;
+            attachmentId?: string;
+            comment?: string;
+            after?: string;
+            [key: string]: unknown;
+        }): Promise<void>;
+    };
+    /** Flush all pending events and traces */
+    flush(): Promise<void>;
+    /** Shutdown the client, flushing all data */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Create a Raindrop Pi Agent client for automatic telemetry capture.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from "@mariozechner/pi-agent-core";
+ * import { createRaindropPiAgent } from "@raindrop-ai/pi-agent";
+ *
+ * const raindrop = createRaindropPiAgent({
+ *   writeKey: "rk_...",
+ *   userId: "user-123",
+ *   convoId: "session-abc",
+ * });
+ *
+ * const agent = new Agent({ ... });
+ * const unsub = raindrop.subscribe(agent);
+ *
+ * await agent.prompt("Hello!");
+ * await raindrop.shutdown();
+ * ```
+ */
+declare function createRaindropPiAgent(opts: RaindropPiAgentOptions): RaindropPiAgentClient;
+
+export { Attachment, type PiAgentSubscribeOptions, type RaindropPiAgentClient, type RaindropPiAgentOptions, createRaindropPiAgent };

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { Agent } from '@mariozechner/pi-agent-core';
+import { A as Attachment } from './index.d-npTVS9Mf.js';
+
+/**
+ * Options for the Raindrop Pi Agent client.
+ */
+interface RaindropPiAgentOptions {
+    /**
+     * Write key for direct authentication.
+     * Optional — when omitted, telemetry shipping is disabled with a warning.
+     */
+    writeKey?: string;
+    /** API endpoint URL (defaults to production) */
+    endpoint?: string;
+    /** Default user ID for all events */
+    userId?: string;
+    /** Default conversation ID to group related events */
+    convoId?: string;
+    /** Default event name (default: "pi_agent_prompt") */
+    eventName?: string;
+    /** Default properties attached to every event */
+    properties?: Record<string, unknown>;
+    /** Trace shipping configuration */
+    traces?: {
+        /** Enable trace shipping (default: true) */
+        enabled?: boolean;
+        /** Flush interval in milliseconds */
+        flushIntervalMs?: number;
+        /** Maximum batch size */
+        maxBatchSize?: number;
+        /** Maximum queue size */
+        maxQueueSize?: number;
+        /** Enable debug logging */
+        debug?: boolean;
+        /** Enable detailed span logging */
+        debugSpans?: boolean;
+    };
+    /** Event shipping configuration */
+    events?: {
+        /** Enable event shipping (default: true) */
+        enabled?: boolean;
+        /** Partial flush interval in milliseconds */
+        partialFlushMs?: number;
+        /** Enable debug logging */
+        debug?: boolean;
+    };
+}
+/**
+ * Per-subscribe overrides for context.
+ */
+interface PiAgentSubscribeOptions {
+    /** User ID override for this subscription */
+    userId?: string;
+    /** Conversation ID override */
+    convoId?: string;
+    /** Event name override */
+    eventName?: string;
+    /** Additional properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * The Raindrop Pi Agent client.
+ * Exposes the full API surface: subscribe, events, users, signals, flush, shutdown.
+ */
+interface RaindropPiAgentClient {
+    /**
+     * Subscribe to a Pi Agent instance for automatic telemetry.
+     * Returns an unsubscribe function.
+     *
+     * @param agent - The Pi Agent instance to observe
+     * @param options - Optional per-subscription overrides
+     * @returns Unsubscribe function to stop tracking
+     */
+    subscribe(agent: Agent, options?: PiAgentSubscribeOptions): () => void;
+    /** Event management methods */
+    events: {
+        /** Patch an existing event with additional data */
+        patch(eventId: string, data: Record<string, unknown>): Promise<void>;
+        /** Add attachments to an event */
+        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+        /** Set properties on an event */
+        setProperties(eventId: string, properties: Record<string, unknown>): Promise<void>;
+        /** Finish an event (trigger immediate shipping) */
+        finish(eventId: string): Promise<void>;
+    };
+    /** User identification methods */
+    users: {
+        /** Identify a user with traits */
+        identify(params: {
+            userId: string;
+            traits?: Record<string, unknown>;
+        }): Promise<void>;
+    };
+    /** Signal tracking methods */
+    signals: {
+        /** Track a signal (feedback, user action, etc.) */
+        track(params: {
+            eventId?: string;
+            name: string;
+            type?: "default" | "feedback" | "edit";
+            sentiment?: "POSITIVE" | "NEGATIVE";
+            timestamp?: string;
+            attachmentId?: string;
+            comment?: string;
+            after?: string;
+            [key: string]: unknown;
+        }): Promise<void>;
+    };
+    /** Flush all pending events and traces */
+    flush(): Promise<void>;
+    /** Shutdown the client, flushing all data */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Create a Raindrop Pi Agent client for automatic telemetry capture.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from "@mariozechner/pi-agent-core";
+ * import { createRaindropPiAgent } from "@raindrop-ai/pi-agent";
+ *
+ * const raindrop = createRaindropPiAgent({
+ *   writeKey: "rk_...",
+ *   userId: "user-123",
+ *   convoId: "session-abc",
+ * });
+ *
+ * const agent = new Agent({ ... });
+ * const unsub = raindrop.subscribe(agent);
+ *
+ * await agent.prompt("Hello!");
+ * await raindrop.shutdown();
+ * ```
+ */
+declare function createRaindropPiAgent(opts: RaindropPiAgentOptions): RaindropPiAgentClient;
+
+export { Attachment, type PiAgentSubscribeOptions, type RaindropPiAgentClient, type RaindropPiAgentOptions, createRaindropPiAgent };