@raindrop-ai/pi-agent 0.0.2

package/dist/extension.d.cts

@@ -0,0 +1,60 @@
+import { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { E as EventShipper$1, T as TraceShipper$1, O as OtlpSpan } from './index.d-npTVS9Mf.cjs';
+
+interface EventMetadata {
+    userId?: string;
+    eventName?: string;
+    properties?: Record<string, unknown>;
+}
+interface RaindropExtensionConfig {
+    writeKey: string;
+    endpoint: string;
+    eventName: string;
+    debug: boolean;
+    captureSystemPrompt: boolean;
+    eventMetadata?: EventMetadata;
+}
+
+declare class EventShipper extends EventShipper$1 {
+    constructor(opts: ConstructorParameters<typeof EventShipper$1>[0]);
+}
+declare class TraceShipper extends TraceShipper$1 {
+    constructor(opts: ConstructorParameters<typeof TraceShipper$1>[0]);
+    enqueue(span: OtlpSpan): void;
+}
+
+/**
+ * Pi Coding Agent extension hooks for Raindrop observability.
+ *
+ * Adapted from KM's pi-extension implementation with enhancements:
+ * - 4-level trace hierarchy (session -> turn -> LLM -> tool)
+ * - LLM-to-tool parenting (tools nest under the LLM span that requested them)
+ * - Shared shipper/helpers with the subscriber entry point
+ */
+
+declare function registerTracing(pi: ExtensionAPI, config: RaindropExtensionConfig, eventShipper: EventShipper, traceShipper: TraceShipper): void;
+
+/**
+ * Pi Coding Agent extension entry point.
+ *
+ * Usage:
+ *   pi install npm:@raindrop-ai/pi-agent
+ *
+ * Or in ~/.pi/agent/extensions/:
+ *   import extension from "@raindrop-ai/pi-agent/extension";
+ *   export default extension;
+ *
+ * Configuration via env vars or JSON config files:
+ *   RAINDROP_WRITE_KEY — required for telemetry
+ *   RAINDROP_API_URL — custom endpoint (default: https://api.raindrop.ai/v1)
+ *   RAINDROP_DEBUG — enable debug logging
+ *   RAINDROP_CAPTURE_SYSTEM_PROMPT — capture system prompts in traces
+ *
+ * Config file locations:
+ *   ~/.pi/agent/raindrop.json (global)
+ *   .pi/raindrop.json (project)
+ */
+
+declare function extension(pi: ExtensionAPI): void;
+
+export { type EventMetadata, type RaindropExtensionConfig, extension as default, registerTracing };

package/dist/extension.d.ts

@@ -0,0 +1,60 @@
+import { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { E as EventShipper$1, T as TraceShipper$1, O as OtlpSpan } from './index.d-npTVS9Mf.js';
+
+interface EventMetadata {
+    userId?: string;
+    eventName?: string;
+    properties?: Record<string, unknown>;
+}
+interface RaindropExtensionConfig {
+    writeKey: string;
+    endpoint: string;
+    eventName: string;
+    debug: boolean;
+    captureSystemPrompt: boolean;
+    eventMetadata?: EventMetadata;
+}
+
+declare class EventShipper extends EventShipper$1 {
+    constructor(opts: ConstructorParameters<typeof EventShipper$1>[0]);
+}
+declare class TraceShipper extends TraceShipper$1 {
+    constructor(opts: ConstructorParameters<typeof TraceShipper$1>[0]);
+    enqueue(span: OtlpSpan): void;
+}
+
+/**
+ * Pi Coding Agent extension hooks for Raindrop observability.
+ *
+ * Adapted from KM's pi-extension implementation with enhancements:
+ * - 4-level trace hierarchy (session -> turn -> LLM -> tool)
+ * - LLM-to-tool parenting (tools nest under the LLM span that requested them)
+ * - Shared shipper/helpers with the subscriber entry point
+ */
+
+declare function registerTracing(pi: ExtensionAPI, config: RaindropExtensionConfig, eventShipper: EventShipper, traceShipper: TraceShipper): void;
+
+/**
+ * Pi Coding Agent extension entry point.
+ *
+ * Usage:
+ *   pi install npm:@raindrop-ai/pi-agent
+ *
+ * Or in ~/.pi/agent/extensions/:
+ *   import extension from "@raindrop-ai/pi-agent/extension";
+ *   export default extension;
+ *
+ * Configuration via env vars or JSON config files:
+ *   RAINDROP_WRITE_KEY — required for telemetry
+ *   RAINDROP_API_URL — custom endpoint (default: https://api.raindrop.ai/v1)
+ *   RAINDROP_DEBUG — enable debug logging
+ *   RAINDROP_CAPTURE_SYSTEM_PROMPT — capture system prompts in traces
+ *
+ * Config file locations:
+ *   ~/.pi/agent/raindrop.json (global)
+ *   .pi/raindrop.json (project)
+ */
+
+declare function extension(pi: ExtensionAPI): void;
+
+export { type EventMetadata, type RaindropExtensionConfig, extension as default, registerTracing };

package/dist/extension.js

@@ -0,0 +1,452 @@
+import {
+  EventShipper,
+  TraceShipper,
+  attrInt,
+  attrString,
+  extractAssistantText,
+  formatToolSpanName,
+  generateId,
+  getHostname,
+  getUsername,
+  libraryVersion,
+  nowUnixNanoString,
+  safeStringify,
+  truncate
+} from "./chunk-LZIGXU2D.js";
+
+// src/internal/config.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function getPiAgentDirectory() {
+  var _a;
+  return (_a = process.env["PI_CODING_AGENT_DIR"]) != null ? _a : join(homedir(), ".pi", "agent");
+}
+function loadConfig(projectDirectory) {
+  var _a, _b, _c, _d, _e, _f, _g;
+  let merged = {};
+  const configPaths = [
+    join(getPiAgentDirectory(), "raindrop.json"),
+    join(projectDirectory, ".pi", "raindrop.json")
+  ];
+  for (const configPath of configPaths) {
+    try {
+      if (existsSync(configPath)) {
+        const content = readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(content);
+        merged = { ...merged, ...parsed };
+      }
+    } catch (e) {
+    }
+  }
+  let eventMetadata;
+  const envMeta = process.env["RAINDROP_EVENT_METADATA"];
+  if (envMeta) {
+    try {
+      eventMetadata = JSON.parse(envMeta);
+    } catch (e) {
+    }
+  }
+  return {
+    writeKey: (_b = (_a = process.env["RAINDROP_WRITE_KEY"]) != null ? _a : merged.write_key) != null ? _b : "",
+    endpoint: (_d = (_c = process.env["RAINDROP_API_URL"]) != null ? _c : merged.api_url) != null ? _d : "https://api.raindrop.ai/v1",
+    eventName: (_e = merged.event_name) != null ? _e : "pi_session",
+    debug: process.env["RAINDROP_DEBUG"] === "true" ? true : (_f = merged.debug) != null ? _f : false,
+    captureSystemPrompt: process.env["RAINDROP_CAPTURE_SYSTEM_PROMPT"] !== void 0 ? process.env["RAINDROP_CAPTURE_SYSTEM_PROMPT"] === "true" : (_g = merged.capture_system_prompt) != null ? _g : false,
+    eventMetadata
+  };
+}
+
+// src/internal/extension-tracing.ts
+function safeParsArgs(argsStr) {
+  try {
+    return JSON.parse(argsStr);
+  } catch (e) {
+    return void 0;
+  }
+}
+var MAX_SYSTEM_PROMPT_LENGTH = 32768;
+function createSessionState(sessionId) {
+  return {
+    sessionId,
+    currentInput: "",
+    turnNumber: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheReadTokens: 0,
+    toolSpanStarts: /* @__PURE__ */ new Map(),
+    toolCallToLlmParent: /* @__PURE__ */ new Map()
+  };
+}
+function getUserId(state, metadata) {
+  var _a;
+  return (_a = metadata == null ? void 0 : metadata.userId) != null ? _a : state.sessionId;
+}
+function getEventName(config) {
+  var _a, _b;
+  return (_b = (_a = config.eventMetadata) == null ? void 0 : _a.eventName) != null ? _b : config.eventName;
+}
+function truncateSystemPrompt(systemPrompt) {
+  if (systemPrompt.length <= MAX_SYSTEM_PROMPT_LENGTH) return systemPrompt;
+  const suffix = "\n...[truncated]";
+  return systemPrompt.slice(0, MAX_SYSTEM_PROMPT_LENGTH - suffix.length) + suffix;
+}
+function getBaseProperties(config, ctx) {
+  var _a;
+  return {
+    workspace: ctx.cwd,
+    directory: ctx.cwd,
+    hostname: getHostname(),
+    os: process.platform,
+    username: getUsername(),
+    sdk_version: libraryVersion,
+    ...(_a = config.eventMetadata) == null ? void 0 : _a.properties
+  };
+}
+function getSystemPromptAttributes(systemPrompt) {
+  if (!systemPrompt) return [];
+  return [
+    attrString("gen_ai.prompt.0.role", "system"),
+    attrString("gen_ai.prompt.0.content", systemPrompt)
+  ];
+}
+function getAssistantText(message) {
+  var _a;
+  return (_a = extractAssistantText(message)) != null ? _a : "";
+}
+function getAssistantError(message) {
+  var _a;
+  if (message.role !== "assistant") return void 0;
+  if (message.stopReason !== "error" && message.stopReason !== "aborted") return void 0;
+  return (_a = message.errorMessage) != null ? _a : `Assistant ${message.stopReason}`;
+}
+function getState(stateRef, ctx) {
+  const sessionId = ctx.sessionManager.getSessionId();
+  if (!stateRef.current || stateRef.current.sessionId !== sessionId) {
+    stateRef.current = createSessionState(sessionId);
+  }
+  return stateRef.current;
+}
+function registerTracing(pi, config, eventShipper, traceShipper) {
+  const stateRef = {};
+  function logError(hook, err) {
+    console.log(
+      `[raindrop-ai/pi-agent] [error] Error in ${hook}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  function startTurnSpan(state) {
+    if (!state.currentEventId || !state.currentRootSpan) return;
+    if (state.currentTurnSpan) {
+      traceShipper.endSpan(state.currentTurnSpan);
+    }
+    state.turnNumber += 1;
+    state.currentTurnSpan = traceShipper.startSpan({
+      name: `Turn ${state.turnNumber}`,
+      parent: state.currentRootSpan.ids,
+      eventId: state.currentEventId,
+      attributes: [
+        attrString("ai.operationId", "ai.turn"),
+        attrInt("ai.turn_number", state.turnNumber)
+      ]
+    });
+  }
+  function ensureTurnSpan(state) {
+    if (state.currentTurnSpan) return;
+    startTurnSpan(state);
+  }
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      stateRef.current = createSessionState(ctx.sessionManager.getSessionId());
+    } catch (err) {
+      logError("session_start", err);
+    }
+  });
+  pi.on("before_agent_start", async (event, ctx) => {
+    var _a, _b, _c;
+    try {
+      const state = getState(stateRef, ctx);
+      if (state.currentTurnSpan) {
+        traceShipper.endSpan(state.currentTurnSpan);
+        state.currentTurnSpan = void 0;
+      }
+      if (state.currentRootSpan) {
+        traceShipper.endSpan(state.currentRootSpan, { error: "Previous run was not finalized" });
+        state.currentRootSpan = void 0;
+      }
+      if (state.currentEventId) {
+        await eventShipper.finish((_a = state.currentEventRequestId) != null ? _a : state.currentEventId, {
+          userId: getUserId(state, config.eventMetadata),
+          properties: { sdk_version: libraryVersion, incomplete: true }
+        });
+        state.currentEventRequestId = void 0;
+        state.currentEventId = void 0;
+      }
+      state.toolSpanStarts.clear();
+      state.toolCallToLlmParent.clear();
+      state.currentInput = event.prompt;
+      state.turnNumber = 0;
+      state.currentSystemPrompt = config.captureSystemPrompt ? truncateSystemPrompt(event.systemPrompt) : void 0;
+      state.currentEventRequestId = generateId();
+      state.totalInputTokens = 0;
+      state.totalOutputTokens = 0;
+      state.totalCacheReadTokens = 0;
+      const attachments = (_c = (_b = event.images) == null ? void 0 : _b.map((image, index) => {
+        var _a2, _b2;
+        return {
+          type: "image",
+          role: "input",
+          name: `image-${index + 1}.${(_b2 = (_a2 = image.mimeType.split("/")[1]) == null ? void 0 : _a2.split("+")[0]) != null ? _b2 : "png"}`,
+          value: `data:${image.mimeType};base64,${image.data}`
+        };
+      })) != null ? _c : [];
+      await eventShipper.patch(state.currentEventRequestId, {
+        isPending: true,
+        userId: getUserId(state, config.eventMetadata),
+        convoId: state.sessionId,
+        eventName: getEventName(config),
+        input: event.prompt,
+        ...attachments.length > 0 ? { attachments } : {},
+        properties: getBaseProperties(config, ctx)
+      });
+      await eventShipper.flush();
+      state.currentEventId = state.currentEventRequestId;
+      state.currentRootSpan = traceShipper.startSpan({
+        name: "ai.event",
+        eventId: state.currentEventId,
+        attributes: [
+          attrString("ai.prompt", truncate(state.currentInput)),
+          attrString("workspace", ctx.cwd),
+          attrString("hostname", getHostname()),
+          attrString("os", process.platform),
+          attrString("username", getUsername())
+        ]
+      });
+    } catch (err) {
+      logError("before_agent_start", err);
+    }
+  });
+  pi.on("turn_start", async (_event, ctx) => {
+    try {
+      const state = getState(stateRef, ctx);
+      startTurnSpan(state);
+    } catch (err) {
+      logError("turn_start", err);
+    }
+  });
+  pi.on("turn_end", async (_event, ctx) => {
+    try {
+      const state = getState(stateRef, ctx);
+      if (!state.currentTurnSpan) return;
+      traceShipper.endSpan(state.currentTurnSpan);
+      state.currentTurnSpan = void 0;
+    } catch (err) {
+      logError("turn_end", err);
+    }
+  });
+  pi.on("message_end", async (event, ctx) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    try {
+      if (((_a = event.message) == null ? void 0 : _a.role) !== "assistant") return;
+      const state = getState(stateRef, ctx);
+      if (!state.currentEventId || !state.currentRootSpan) return;
+      ensureTurnSpan(state);
+      const message = event.message;
+      const provider = (_b = message.provider) != null ? _b : "";
+      const modelId = (_c = message.model) != null ? _c : "";
+      const modelName = provider && modelId ? `${provider}/${modelId}` : modelId || "llm";
+      const errorForSpan = getAssistantError(message);
+      const outputText = getAssistantText(message);
+      const inputTokens = (_d = message.usage) == null ? void 0 : _d.input;
+      const outputTokens = (_e = message.usage) == null ? void 0 : _e.output;
+      const cacheReadTokens = (_f = message.usage) == null ? void 0 : _f.cacheRead;
+      if (typeof inputTokens === "number") state.totalInputTokens += inputTokens;
+      if (typeof outputTokens === "number") state.totalOutputTokens += outputTokens;
+      if (typeof cacheReadTokens === "number" && cacheReadTokens > 0) state.totalCacheReadTokens += cacheReadTokens;
+      const turnParent = (_g = state.currentTurnSpan) != null ? _g : state.currentRootSpan;
+      const llmAttrs = [
+        attrString("ai.operationId", "generateText"),
+        provider ? attrString("gen_ai.system", provider) : void 0,
+        modelId ? attrString("gen_ai.request.model", modelId) : void 0,
+        modelId ? attrString("gen_ai.response.model", modelId) : void 0,
+        typeof inputTokens === "number" ? attrInt("gen_ai.usage.input_tokens", inputTokens) : void 0,
+        typeof outputTokens === "number" ? attrInt("gen_ai.usage.output_tokens", outputTokens) : void 0,
+        typeof cacheReadTokens === "number" && cacheReadTokens > 0 ? attrInt("gen_ai.usage.cache_read_tokens", cacheReadTokens) : void 0,
+        outputText ? attrString("ai.response.text", truncate(outputText)) : void 0,
+        state.currentInput ? attrString("ai.prompt", truncate(state.currentInput)) : void 0,
+        message.stopReason ? attrString("ai.stop_reason", message.stopReason) : void 0,
+        ...getSystemPromptAttributes(state.currentSystemPrompt)
+      ].filter(Boolean);
+      const llmSpan = traceShipper.startSpan({
+        name: modelName,
+        parent: turnParent.ids,
+        eventId: state.currentEventId,
+        attributes: llmAttrs
+      });
+      traceShipper.endSpan(llmSpan, errorForSpan ? { error: errorForSpan } : void 0);
+      if (Array.isArray(message.content)) {
+        for (const part of message.content) {
+          if (part && typeof part === "object" && part.type === "toolCall" && typeof part.id === "string") {
+            state.toolCallToLlmParent.set(part.id, llmSpan.ids);
+          }
+        }
+      }
+      if (message.stopReason === "toolUse") {
+        await traceShipper.flush();
+        return;
+      }
+      if (state.currentTurnSpan) {
+        traceShipper.endSpan(state.currentTurnSpan);
+        state.currentTurnSpan = void 0;
+      }
+      state.currentRootSpan.name = modelName;
+      traceShipper.endSpan(state.currentRootSpan, {
+        attributes: [
+          ...modelId ? [attrString("gen_ai.response.model", modelId)] : [],
+          ...outputText ? [attrString("ai.response.text", truncate(outputText))] : [],
+          attrInt("ai.total_turns", state.turnNumber)
+        ],
+        ...errorForSpan ? { error: errorForSpan } : {}
+      });
+      state.currentRootSpan = void 0;
+      await eventShipper.finish((_h = state.currentEventRequestId) != null ? _h : state.currentEventId, {
+        userId: getUserId(state, config.eventMetadata),
+        model: modelName,
+        ...outputText.trim() ? { output: outputText } : {},
+        properties: {
+          sdk_version: libraryVersion,
+          stop_reason: message.stopReason,
+          ...state.totalInputTokens > 0 ? { "ai.usage.prompt_tokens": state.totalInputTokens } : {},
+          ...state.totalOutputTokens > 0 ? { "ai.usage.completion_tokens": state.totalOutputTokens } : {},
+          ...state.totalCacheReadTokens > 0 ? { "ai.usage.cache_read_tokens": state.totalCacheReadTokens } : {}
+        }
+      });
+      state.currentEventRequestId = void 0;
+      state.currentEventId = void 0;
+      state.toolSpanStarts.clear();
+      state.toolCallToLlmParent.clear();
+      await traceShipper.flush();
+    } catch (err) {
+      logError("message_end", err);
+    }
+  });
+  pi.on("tool_execution_start", async (event, ctx) => {
+    var _a, _b, _c;
+    try {
+      const state = getState(stateRef, ctx);
+      if (!state.currentEventId || !state.currentRootSpan) return;
+      const llmParent = state.toolCallToLlmParent.get(event.toolCallId);
+      const parent = (_b = llmParent != null ? llmParent : (_a = state.currentTurnSpan) == null ? void 0 : _a.ids) != null ? _b : state.currentRootSpan.ids;
+      state.toolSpanStarts.set(event.toolCallId, {
+        startTimeUnixNano: nowUnixNanoString(),
+        parent,
+        eventId: state.currentEventId,
+        name: event.toolName,
+        args: (_c = safeStringify(event.args)) != null ? _c : "{}"
+      });
+    } catch (err) {
+      logError("tool_execution_start", err);
+    }
+  });
+  pi.on("tool_execution_end", async (event, ctx) => {
+    try {
+      const state = getState(stateRef, ctx);
+      const start = state.toolSpanStarts.get(event.toolCallId);
+      if (!start) return;
+      state.toolSpanStarts.delete(event.toolCallId);
+      state.toolCallToLlmParent.delete(event.toolCallId);
+      const resultStr = safeStringify(event.result);
+      traceShipper.createSpan({
+        name: formatToolSpanName(start.name, safeParsArgs(start.args)),
+        parent: start.parent,
+        eventId: start.eventId,
+        startTimeUnixNano: start.startTimeUnixNano,
+        endTimeUnixNano: nowUnixNanoString(),
+        attributes: [
+          attrString("ai.operationId", "ai.toolCall"),
+          attrString("ai.toolCall.name", start.name),
+          attrString("ai.toolCall.id", event.toolCallId),
+          attrString("ai.toolCall.args", truncate(start.args)),
+          ...resultStr ? [attrString("ai.toolCall.result", truncate(resultStr))] : []
+        ],
+        ...event.isError ? { status: { code: 2, message: `Tool "${start.name}" failed` } } : {}
+      });
+    } catch (err) {
+      logError("tool_execution_end", err);
+    }
+  });
+  pi.on("agent_end", async (_event, ctx) => {
+    var _a;
+    try {
+      const state = getState(stateRef, ctx);
+      if (state.currentTurnSpan) {
+        traceShipper.endSpan(state.currentTurnSpan);
+        state.currentTurnSpan = void 0;
+      }
+      if (state.currentRootSpan) {
+        traceShipper.endSpan(state.currentRootSpan, {
+          error: "Agent ended before a final assistant response was recorded"
+        });
+        state.currentRootSpan = void 0;
+      }
+      if (state.currentEventId) {
+        await eventShipper.finish((_a = state.currentEventRequestId) != null ? _a : state.currentEventId, {
+          userId: getUserId(state, config.eventMetadata),
+          properties: {
+            sdk_version: libraryVersion,
+            incomplete: true
+          }
+        });
+        state.currentEventRequestId = void 0;
+        state.currentEventId = void 0;
+      }
+      state.toolSpanStarts.clear();
+      state.toolCallToLlmParent.clear();
+      await Promise.all([eventShipper.flush(), traceShipper.flush()]);
+    } catch (err) {
+      logError("agent_end", err);
+    }
+  });
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    try {
+      stateRef.current = void 0;
+      await Promise.all([eventShipper.shutdown(), traceShipper.shutdown()]);
+    } catch (err) {
+      logError("session_shutdown", err);
+    }
+  });
+}
+
+// src/extension.ts
+var PLUGIN_NAME = "@raindrop-ai/pi-agent";
+function extension(pi) {
+  const config = loadConfig(process.cwd());
+  function appLog(level, message) {
+    console.log(`[raindrop-ai/pi-agent] [${level}] ${message}`);
+  }
+  appLog("info", `Loading ${PLUGIN_NAME} v${libraryVersion}`);
+  if (!config.writeKey) {
+    appLog(
+      "warn",
+      "RAINDROP_WRITE_KEY not set \u2014 Raindrop tracing disabled. Set it in your environment or in ~/.pi/agent/raindrop.json."
+    );
+    return;
+  }
+  if (config.debug) {
+    appLog("info", `Raindrop tracing enabled (endpoint: ${config.endpoint})`);
+  }
+  const eventShipper = new EventShipper({
+    writeKey: config.writeKey,
+    endpoint: config.endpoint,
+    debug: config.debug
+  });
+  const traceShipper = new TraceShipper({
+    writeKey: config.writeKey,
+    endpoint: config.endpoint,
+    debug: config.debug
+  });
+  registerTracing(pi, config, eventShipper, traceShipper);
+}
+export {
+  extension as default,
+  registerTracing
+};