@firstflow/core 0.0.6 → 0.0.9

package/dist/langchain.mjs

@@ -0,0 +1,277 @@
+import {
+  getRuntime
+} from "./chunk-QBEGXT76.mjs";
+
+// src/langchain.ts
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+function asString(v) {
+  return typeof v === "string" ? v.trim() : "";
+}
+var warnedIncompleteTagging = false;
+function warnIncompleteOnce() {
+  if (warnedIncompleteTagging) return;
+  warnedIncompleteTagging = true;
+  console.warn(
+    "[@firstflow/core/langchain] A LangChain run was tagged with some but not all of `firstflowAgentId`, `sessionId`, `userId` \u2014 the turn was NOT observed. Provide all three in the run metadata to track it."
+  );
+}
+function readIdentity(metadata) {
+  if (!metadata) return void 0;
+  const nested = typeof metadata.firstflow === "object" && metadata.firstflow !== null ? metadata.firstflow : {};
+  const agentId = asString(metadata.firstflowAgentId ?? nested.agentId);
+  const sessionId = asString(metadata.sessionId ?? nested.sessionId);
+  const userId = asString(metadata.userId ?? nested.userId);
+  if (!agentId && !sessionId && !userId) return void 0;
+  if (!agentId || !sessionId || !userId) {
+    warnIncompleteOnce();
+    return void 0;
+  }
+  return { agentId, sessionId, userId };
+}
+var KNOWN_PROVIDERS = /* @__PURE__ */ new Set(["openai", "anthropic"]);
+function roleOf(msg) {
+  if (!msg || typeof msg !== "object") return void 0;
+  const m = msg;
+  let t;
+  if (typeof m._getType === "function") t = m._getType();
+  else if (typeof m.getType === "function") t = m.getType();
+  else if (typeof m.role === "string") t = m.role;
+  else if (typeof m.type === "string") t = m.type;
+  switch (t) {
+    case "human":
+    case "user":
+      return "user";
+    case "ai":
+    case "assistant":
+      return "assistant";
+    case "tool":
+    case "function":
+      return "tool";
+    default:
+      return void 0;
+  }
+}
+function contentToText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  let acc = "";
+  for (const part of content) {
+    if (typeof part === "string") {
+      acc += part;
+    } else if (part && typeof part === "object") {
+      const p = part;
+      if (p.type === "text" && typeof p.text === "string") acc += p.text;
+    }
+  }
+  return acc;
+}
+function toRecentMessages(messages) {
+  if (!Array.isArray(messages)) return [];
+  const out = [];
+  for (const msg of messages) {
+    const role = roleOf(msg);
+    if (role !== "user" && role !== "assistant") continue;
+    const content = contentToText(msg.content).trim();
+    if (!content) continue;
+    out.push({ role, content });
+  }
+  return out;
+}
+function turnStartUserMessage(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return void 0;
+  const last = messages[messages.length - 1];
+  if (roleOf(last) !== "user") return void 0;
+  const text = contentToText(last.content).trim();
+  return text || void 0;
+}
+function extractModel(extraParams, metadata) {
+  const inv = extraParams?.invocation_params ?? {};
+  const fromInv = inv.model ?? inv.model_name ?? inv.modelName;
+  if (typeof fromInv === "string" && fromInv) return fromInv;
+  const fromMeta = metadata?.ls_model_name;
+  return typeof fromMeta === "string" && fromMeta ? fromMeta : void 0;
+}
+function extractProvider(metadata) {
+  const p = metadata?.ls_provider;
+  return typeof p === "string" && KNOWN_PROVIDERS.has(p) ? p : void 0;
+}
+function extractEndMeta(output) {
+  const out = output ?? {};
+  const generations = out.generations;
+  let text = "";
+  const meta = {};
+  if (Array.isArray(generations)) {
+    for (const promptGens of generations) {
+      if (!Array.isArray(promptGens)) continue;
+      for (const gen of promptGens) {
+        if (!gen || typeof gen !== "object") continue;
+        const g = gen;
+        if (typeof g.text === "string" && g.text) text += g.text;
+        const message = g.message;
+        if (message) {
+          if (!text) text += contentToText(message.content);
+          const usage = message.usage_metadata;
+          if (usage) {
+            if (typeof usage.input_tokens === "number") meta.inputTokens = usage.input_tokens;
+            if (typeof usage.output_tokens === "number") meta.outputTokens = usage.output_tokens;
+            const inDetails = usage.input_token_details;
+            if (typeof inDetails?.cache_read === "number") meta.cacheReadTokens = inDetails.cache_read;
+            if (typeof inDetails?.cache_creation === "number")
+              meta.cacheCreationTokens = inDetails.cache_creation;
+          }
+          const respMeta = message.response_metadata;
+          const stop = respMeta?.stop_reason ?? respMeta?.finish_reason;
+          if (typeof stop === "string" && meta.finishReason === void 0) meta.finishReason = stop;
+        }
+        const genInfo = g.generationInfo;
+        const fr = genInfo?.finish_reason ?? genInfo?.finishReason;
+        if (typeof fr === "string" && meta.finishReason === void 0) meta.finishReason = fr;
+      }
+    }
+  }
+  if (meta.inputTokens === void 0 || meta.outputTokens === void 0) {
+    const llmOutput = out.llmOutput ?? {};
+    const usage = llmOutput.tokenUsage ?? llmOutput.usage ?? {};
+    const input = usage.promptTokens ?? usage.input_tokens ?? usage.prompt_tokens;
+    const outp = usage.completionTokens ?? usage.output_tokens ?? usage.completion_tokens;
+    if (meta.inputTokens === void 0 && typeof input === "number") meta.inputTokens = input;
+    if (meta.outputTokens === void 0 && typeof outp === "number") meta.outputTokens = outp;
+  }
+  return { text, meta };
+}
+function safeObserve(fn) {
+  try {
+    fn();
+  } catch (err) {
+    warnRuntimeOnce(err);
+  }
+}
+var warnedRuntime = false;
+function warnRuntimeOnce(err) {
+  if (warnedRuntime) return;
+  warnedRuntime = true;
+  console.warn(
+    `[@firstflow/core/langchain] Telemetry disabled: ${err instanceof Error ? err.message : String(err)}`
+  );
+}
+var FirstflowCallbackHandler = class extends BaseCallbackHandler {
+  name = "firstflow";
+  runs = /* @__PURE__ */ new Map();
+  // -- starts ----------------------------------------------------------------
+  handleChatModelStart(_llm, messages, runId, _parentRunId, extraParams, _tags, metadata) {
+    const identity = readIdentity(metadata);
+    if (!identity) return;
+    const prompt = Array.isArray(messages) ? messages[0] : messages;
+    this.begin(runId, identity, prompt, extraParams, metadata);
+  }
+  handleLLMStart(_llm, prompts, runId, _parentRunId, extraParams, _tags, metadata) {
+    const identity = readIdentity(metadata);
+    if (!identity) return;
+    const list = Array.isArray(prompts) ? prompts : [];
+    const last = list.length ? list[list.length - 1] : void 0;
+    const pseudo = typeof last === "string" ? [{ role: "user", content: last }] : [];
+    this.begin(runId, identity, pseudo, extraParams, metadata);
+  }
+  begin(runId, identity, prompt, extraParams, metadata) {
+    const recentMessages = toRecentMessages(prompt);
+    const model = extractModel(extraParams, metadata);
+    const provider = extractProvider(metadata);
+    this.runs.set(runId, {
+      identity,
+      startTime: Date.now(),
+      model,
+      provider,
+      recentMessages
+    });
+    const userContent = turnStartUserMessage(prompt);
+    if (!userContent) return;
+    safeObserve(
+      () => getRuntime().observe({
+        agentId: identity.agentId,
+        conversationId: identity.sessionId,
+        userId: identity.userId,
+        role: "user",
+        content: userContent,
+        model,
+        provider,
+        ...recentMessages.length ? { recentMessages } : {}
+      })
+    );
+  }
+  // -- streaming -------------------------------------------------------------
+  handleLLMNewToken(_token, _idx, runId) {
+    const state = this.runs.get(runId);
+    if (state && state.firstTokenTime === void 0) state.firstTokenTime = Date.now();
+  }
+  // -- ends ------------------------------------------------------------------
+  handleLLMEnd(output, runId) {
+    const state = this.runs.get(runId);
+    if (!state) return;
+    this.runs.delete(runId);
+    const { text, meta } = extractEndMeta(output);
+    const { identity, startTime, firstTokenTime, model, provider, recentMessages } = state;
+    safeObserve(
+      () => getRuntime().observe({
+        agentId: identity.agentId,
+        conversationId: identity.sessionId,
+        userId: identity.userId,
+        role: "assistant",
+        content: text,
+        model,
+        provider,
+        ...meta,
+        latencyMs: Date.now() - startTime,
+        ...firstTokenTime !== void 0 ? { timeToFirstTokenMs: firstTokenTime - startTime } : {},
+        httpStatus: 200,
+        ...recentMessages.length ? { recentMessages } : {}
+      })
+    );
+  }
+  handleLLMError(err, runId) {
+    const state = this.runs.get(runId);
+    if (!state) return;
+    this.runs.delete(runId);
+    const { identity, startTime, model, provider } = state;
+    const status = err?.status;
+    safeObserve(
+      () => getRuntime().observe({
+        agentId: identity.agentId,
+        conversationId: identity.sessionId,
+        userId: identity.userId,
+        role: "assistant",
+        content: "",
+        isError: true,
+        error: err instanceof Error ? err.message : String(err),
+        model,
+        provider,
+        latencyMs: Date.now() - startTime,
+        httpStatus: typeof status === "number" ? status : 500
+      })
+    );
+  }
+};
+var _shared;
+function firstflowCallback() {
+  if (!_shared) _shared = new FirstflowCallbackHandler();
+  return _shared;
+}
+function withFirstflow(identity, config) {
+  const handler = firstflowCallback();
+  const existing = Array.isArray(config?.callbacks) ? config.callbacks : config?.callbacks ? [config.callbacks] : [];
+  const callbacks = existing.includes(handler) ? existing : [...existing, handler];
+  return {
+    ...config,
+    callbacks,
+    metadata: {
+      ...config?.metadata ?? {},
+      firstflowAgentId: identity.agentId,
+      sessionId: identity.sessionId,
+      userId: identity.userId
+    }
+  };
+}
+export {
+  FirstflowCallbackHandler,
+  firstflowCallback,
+  withFirstflow
+};

package/dist/openai.d.mts

@@ -15,5 +15,14 @@ declare module "openai/resources/chat/completions/completions" {
 
 /** Drop-in `OpenAI` client with Firstflow observability built in. */
 declare const OpenAI: typeof RealOpenAI;
+/**
+ * Instance type of the wrapped client, so consumers can annotate naturally:
+ *
+ *   private readonly client: OpenAI = new OpenAI();
+ *
+ * `OpenAI` lives in both the value and type namespaces (the `const` above is the
+ * value; this alias is the type), mirroring how the real SDK's class works.
+ */
+type OpenAI = RealOpenAI;
 
 export { OpenAI };

package/dist/openai.d.ts

@@ -15,5 +15,14 @@ declare module "openai/resources/chat/completions/completions" {
 
 /** Drop-in `OpenAI` client with Firstflow observability built in. */
 declare const OpenAI: typeof RealOpenAI;
+/**
+ * Instance type of the wrapped client, so consumers can annotate naturally:
+ *
+ *   private readonly client: OpenAI = new OpenAI();
+ *
+ * `OpenAI` lives in both the value and type namespaces (the `const` above is the
+ * value; this alias is the type), mirroring how the real SDK's class works.
+ */
+type OpenAI = RealOpenAI;
 
 export { OpenAI };

package/dist/openai.mjs

@@ -1,7 +1,8 @@
 import {
   wrapProvider
-} from "./chunk-RZMKPIBO.mjs";
-import "./chunk-X3T7X4JQ.mjs";
+} from "./chunk-KAH2MUTQ.mjs";
+import "./chunk-WQZUOUMF.mjs";
+import "./chunk-QBEGXT76.mjs";
 
 // src/openai.ts
 import RealOpenAI from "openai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstflow/core",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "Firstflow Node SDK — cloud forwarding, LLM wrap, self-owned analytics",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -20,12 +20,24 @@
       "types": "./dist/anthropic.d.ts",
       "import": "./dist/anthropic.mjs",
       "require": "./dist/anthropic.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.mjs",
+      "require": "./dist/langchain.js"
     }
   },
   "typesVersions": {
     "*": {
-      "openai": ["./dist/openai.d.ts"],
-      "anthropic": ["./dist/anthropic.d.ts"]
+      "openai": [
+        "./dist/openai.d.ts"
+      ],
+      "anthropic": [
+        "./dist/anthropic.d.ts"
+      ],
+      "langchain": [
+        "./dist/langchain.d.ts"
+      ]
     }
   },
   "files": [
@@ -55,6 +67,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.36.0",
+    "@langchain/core": ">=0.3.0",
     "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
@@ -63,10 +76,14 @@
     },
     "@anthropic-ai/sdk": {
       "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.52.0",
+    "@langchain/core": "^0.3.0",
     "@types/node": "^22.0.0",
     "openai": "^4.104.0",
     "tsup": "^8.0.0",
@@ -79,6 +96,8 @@
     "openai",
     "anthropic",
     "claude",
+    "langchain",
+    "langgraph",
     "opentelemetry"
   ]
 }