@raindrop-ai/pi-agent 0.0.2 → 0.0.4

package/dist/{index.d-npTVS9Mf.d.cts → index.d-Cxs_NTx0.d.cts}

@@ -79,6 +79,11 @@ 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;
 };
 declare class EventShipper {
     private baseUrl;
@@ -94,6 +99,8 @@ declare class EventShipper {
     private sticky;
     private timers;
     private inFlight;
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
+    private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
@@ -110,6 +117,23 @@ declare class EventShipper {
     identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
     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;
@@ -130,6 +154,45 @@ 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;
+    /**
+     * 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;
 };
 declare class TraceShipper {
     private baseUrl;
@@ -147,9 +210,26 @@ declare class TraceShipper {
     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;
     constructor(opts: TraceShipperOptions);
+    /**
+     * 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;
     startSpan(args: {
@@ -163,6 +243,7 @@ declare class TraceShipper {
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
     }): InternalSpan;
+    private mirrorToLocalDebugger;
     endSpan(span: InternalSpan, extra?: {
         attributes?: InternalSpan["attributes"];
         error?: unknown;

package/dist/{index.d-npTVS9Mf.d.ts → index.d-Cxs_NTx0.d.ts}

@@ -79,6 +79,11 @@ 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;
 };
 declare class EventShipper {
     private baseUrl;
@@ -94,6 +99,8 @@ declare class EventShipper {
     private sticky;
     private timers;
     private inFlight;
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
+    private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
@@ -110,6 +117,23 @@ declare class EventShipper {
     identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
     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;
@@ -130,6 +154,45 @@ 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;
+    /**
+     * 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;
 };
 declare class TraceShipper {
     private baseUrl;
@@ -147,9 +210,26 @@ declare class TraceShipper {
     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;
     constructor(opts: TraceShipperOptions);
+    /**
+     * 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;
     startSpan(args: {
@@ -163,6 +243,7 @@ declare class TraceShipper {
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
     }): InternalSpan;
+    private mirrorToLocalDebugger;
     endSpan(span: InternalSpan, extra?: {
         attributes?: InternalSpan["attributes"];
         error?: unknown;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Agent } from '@mariozechner/pi-agent-core';
-import { A as Attachment } from './index.d-npTVS9Mf.cjs';
+import { Agent } from '@earendil-works/pi-agent-core';
+import { A as Attachment } from './index.d-Cxs_NTx0.cjs';
 
 /**
  * Options for the Raindrop Pi Agent client.
@@ -20,6 +20,14 @@ interface RaindropPiAgentOptions {
     eventName?: string;
     /** Default properties attached to every event */
     properties?: Record<string, unknown>;
+    /**
+     * Explicit Workshop / local debugger URL forwarded to both shippers as
+     * their `localDebuggerUrl`. `null` opts out (overrides
+     * `RAINDROP_LOCAL_DEBUGGER` / `RAINDROP_WORKSHOP` env vars and
+     * auto-detect). `undefined` falls through to the env / auto-detect
+     * resolution in `@raindrop-ai/core`.
+     */
+    localWorkshopUrl?: string | null;
     /** Trace shipping configuration */
     traces?: {
         /** Enable trace shipping (default: true) */
@@ -117,11 +125,11 @@ interface RaindropPiAgentClient {
  *
  * @example
  * ```typescript
- * import { Agent } from "@mariozechner/pi-agent-core";
+ * import { Agent } from "@earendil-works/pi-agent-core";
  * import { createRaindropPiAgent } from "@raindrop-ai/pi-agent";
  *
  * const raindrop = createRaindropPiAgent({
- *   writeKey: "rk_...",
+ *   writeKey: "your-write-key",
  *   userId: "user-123",
  *   convoId: "session-abc",
  * });

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Agent } from '@mariozechner/pi-agent-core';
-import { A as Attachment } from './index.d-npTVS9Mf.js';
+import { Agent } from '@earendil-works/pi-agent-core';
+import { A as Attachment } from './index.d-Cxs_NTx0.js';
 
 /**
  * Options for the Raindrop Pi Agent client.
@@ -20,6 +20,14 @@ interface RaindropPiAgentOptions {
     eventName?: string;
     /** Default properties attached to every event */
     properties?: Record<string, unknown>;
+    /**
+     * Explicit Workshop / local debugger URL forwarded to both shippers as
+     * their `localDebuggerUrl`. `null` opts out (overrides
+     * `RAINDROP_LOCAL_DEBUGGER` / `RAINDROP_WORKSHOP` env vars and
+     * auto-detect). `undefined` falls through to the env / auto-detect
+     * resolution in `@raindrop-ai/core`.
+     */
+    localWorkshopUrl?: string | null;
     /** Trace shipping configuration */
     traces?: {
         /** Enable trace shipping (default: true) */
@@ -117,11 +125,11 @@ interface RaindropPiAgentClient {
  *
  * @example
  * ```typescript
- * import { Agent } from "@mariozechner/pi-agent-core";
+ * import { Agent } from "@earendil-works/pi-agent-core";
  * import { createRaindropPiAgent } from "@raindrop-ai/pi-agent";
  *
  * const raindrop = createRaindropPiAgent({
- *   writeKey: "rk_...",
+ *   writeKey: "your-write-key",
  *   userId: "user-123",
  *   convoId: "session-abc",
  * });

package/dist/index.js

@@ -13,9 +13,10 @@ import {
   getUsername,
   libraryVersion,
   randomUUID,
+  resolveLocalDebuggerBaseUrl,
   safeStringify,
   truncate
-} from "./chunk-LZIGXU2D.js";
+} from "./chunk-EWIO36KH.js";
 
 // src/internal/subscriber.ts
 function createSubscriber(agent, eventShipper, traceShipper, defaultOptions, options, debug) {
@@ -376,23 +377,26 @@ function envDebugEnabled() {
 function createRaindropPiAgent(opts) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
   const hasWriteKey = typeof opts.writeKey === "string" && opts.writeKey.trim().length > 0;
+  const resolvedLocalUrl = resolveLocalDebuggerBaseUrl(opts.localWorkshopUrl);
+  const hasLocalDestination = resolvedLocalUrl !== null;
   const eventsEnabled = ((_a = opts.events) == null ? void 0 : _a.enabled) !== false;
   const tracesEnabled = ((_b = opts.traces) == null ? void 0 : _b.enabled) !== false;
-  if (!hasWriteKey && !opts.endpoint) {
+  if (!hasWriteKey && !opts.endpoint && !hasLocalDestination) {
     console.warn(
       "[raindrop-ai/pi-agent] writeKey not provided; telemetry shipping is disabled"
     );
   }
   const envDebug = envDebugEnabled();
   const debug = ((_c = opts.events) == null ? void 0 : _c.debug) === true || ((_d = opts.traces) == null ? void 0 : _d.debug) === true || envDebug;
-  const eventShipper = eventsEnabled && (hasWriteKey || opts.endpoint) ? new EventShipper({
+  const eventShipper = eventsEnabled && (hasWriteKey || opts.endpoint || hasLocalDestination) ? new EventShipper({
     writeKey: opts.writeKey,
     endpoint: opts.endpoint,
     enabled: true,
     debug: ((_e = opts.events) == null ? void 0 : _e.debug) === true || envDebug,
-    partialFlushMs: (_f = opts.events) == null ? void 0 : _f.partialFlushMs
+    partialFlushMs: (_f = opts.events) == null ? void 0 : _f.partialFlushMs,
+    localDebuggerUrl: opts.localWorkshopUrl
   }) : null;
-  const traceShipper = tracesEnabled && (hasWriteKey || opts.endpoint) ? new TraceShipper({
+  const traceShipper = tracesEnabled && (hasWriteKey || opts.endpoint || hasLocalDestination) ? new TraceShipper({
     writeKey: opts.writeKey,
     endpoint: opts.endpoint,
     enabled: true,
@@ -400,7 +404,8 @@ function createRaindropPiAgent(opts) {
     debugSpans: ((_h = opts.traces) == null ? void 0 : _h.debugSpans) === true || envDebug,
     flushIntervalMs: (_i = opts.traces) == null ? void 0 : _i.flushIntervalMs,
     maxBatchSize: (_j = opts.traces) == null ? void 0 : _j.maxBatchSize,
-    maxQueueSize: (_k = opts.traces) == null ? void 0 : _k.maxQueueSize
+    maxQueueSize: (_k = opts.traces) == null ? void 0 : _k.maxQueueSize,
+    localDebuggerUrl: opts.localWorkshopUrl
   }) : null;
   const defaultOptions = {
     userId: opts.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raindrop-ai/pi-agent",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Raindrop observability for Pi Agent — automatic tracing via subscriber or pi-coding-agent extension",
   "type": "module",
   "license": "MIT",
@@ -42,31 +42,24 @@
     "dist/**",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "peerDependencies": {
-    "@mariozechner/pi-agent-core": ">=0.60.0",
-    "@mariozechner/pi-coding-agent": ">=0.65.2"
+    "@earendil-works/pi-agent-core": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0"
   },
   "peerDependenciesMeta": {
-    "@mariozechner/pi-coding-agent": {
+    "@earendil-works/pi-coding-agent": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@raindrop-ai/core": "workspace:*",
-    "@mariozechner/pi-agent-core": "^0.66.0",
-    "@mariozechner/pi-coding-agent": "^0.66.0",
+    "@earendil-works/pi-agent-core": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
     "@types/node": "^20.11.17",
     "msw": "^2.12.7",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "@raindrop-ai/core": "0.0.2"
   },
   "tsup": {
     "entry": [
@@ -87,5 +80,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}