@firstflow/core 0.0.7 → 0.0.9

package/dist/chunk-WQZUOUMF.mjs

@@ -0,0 +1,404 @@
+import {
+  context,
+  propagation
+} from "./chunk-QBEGXT76.mjs";
+
+// src/wrap.ts
+var INSTRUMENTED_PATHS = /* @__PURE__ */ new Set([
+  "chat.completions.create",
+  "embeddings.create",
+  "responses.create",
+  "messages.create"
+]);
+var warnedIncompleteTagging = false;
+function parseFirstflowMeta(args) {
+  const nextArgs = [...args];
+  for (let i = 0; i < nextArgs.length; i++) {
+    const a = nextArgs[i];
+    if (typeof a !== "object" || a === null) continue;
+    const rec = a;
+    if (!("firstflowAgentId" in rec) && !("sessionId" in rec) && !("userId" in rec)) {
+      continue;
+    }
+    const agentId = typeof rec.firstflowAgentId === "string" ? rec.firstflowAgentId.trim() : "";
+    const sessionId = typeof rec.sessionId === "string" ? rec.sessionId.trim() : "";
+    const userId = typeof rec.userId === "string" ? rec.userId.trim() : "";
+    const { firstflowAgentId: _a, sessionId: _s, userId: _u, ...rest } = rec;
+    nextArgs[i] = rest;
+    if (!agentId || !sessionId || !userId) {
+      if (!warnedIncompleteTagging) {
+        warnedIncompleteTagging = true;
+        console.warn(
+          "[@firstflow/core] LLM call tagged with some but not all of `firstflowAgentId`, `sessionId`, `userId` \u2014 the call was NOT observed. Provide all three to track it."
+        );
+      }
+      return { nextArgs };
+    }
+    return { nextArgs, meta: { agentId, userId, conversationId: sessionId } };
+  }
+  return { nextArgs };
+}
+function extractModel(nextArgs) {
+  const body = nextArgs[0];
+  if (!body || typeof body !== "object") return void 0;
+  const m = body.model;
+  return typeof m === "string" ? m : void 0;
+}
+function detectProvider(path) {
+  return path === "messages.create" ? "anthropic" : "openai";
+}
+function injectOpenAiStreamUsage(nextArgs) {
+  const body = nextArgs[0];
+  if (!body || typeof body !== "object") return nextArgs;
+  const b = body;
+  if (b.stream !== true) return nextArgs;
+  const existing = b.stream_options ?? {};
+  if (existing.include_usage === true) return nextArgs;
+  const patched = [...nextArgs];
+  patched[0] = { ...b, stream_options: { ...existing, include_usage: true } };
+  return patched;
+}
+function extractOpenAiResponseMeta(res) {
+  const usage = res.usage;
+  const details = usage?.prompt_tokens_details;
+  const choice = Array.isArray(res.choices) ? res.choices[0] : void 0;
+  return {
+    inputTokens: typeof usage?.prompt_tokens === "number" ? usage.prompt_tokens : void 0,
+    outputTokens: typeof usage?.completion_tokens === "number" ? usage.completion_tokens : void 0,
+    cacheReadTokens: typeof details?.cached_tokens === "number" ? details.cached_tokens : void 0,
+    finishReason: typeof choice?.finish_reason === "string" ? choice.finish_reason : void 0
+  };
+}
+function extractAnthropicResponseMeta(res) {
+  const usage = res.usage;
+  return {
+    inputTokens: typeof usage?.input_tokens === "number" ? usage.input_tokens : void 0,
+    outputTokens: typeof usage?.output_tokens === "number" ? usage.output_tokens : void 0,
+    cacheReadTokens: typeof usage?.cache_read_input_tokens === "number" ? usage.cache_read_input_tokens : void 0,
+    cacheCreationTokens: typeof usage?.cache_creation_input_tokens === "number" ? usage.cache_creation_input_tokens : void 0,
+    finishReason: typeof res.stop_reason === "string" ? res.stop_reason : void 0
+  };
+}
+function accumOpenAiStreamChunkMeta(chunk, acc) {
+  if (!chunk || typeof chunk !== "object") return;
+  const c = chunk;
+  if (c.usage && typeof c.usage === "object") {
+    const usage = c.usage;
+    const details = usage.prompt_tokens_details;
+    if (typeof usage.prompt_tokens === "number") acc.inputTokens = usage.prompt_tokens;
+    if (typeof usage.completion_tokens === "number") acc.outputTokens = usage.completion_tokens;
+    if (typeof details?.cached_tokens === "number") acc.cacheReadTokens = details.cached_tokens;
+  }
+  if (Array.isArray(c.choices) && c.choices[0]) {
+    const choice = c.choices[0];
+    if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+      acc.finishReason = choice.finish_reason;
+    }
+  }
+}
+function accumAnthropicStreamChunkMeta(chunk, acc) {
+  if (!chunk || typeof chunk !== "object") return;
+  const c = chunk;
+  if (c.type === "message_start") {
+    const msg = c.message;
+    const usage = msg?.usage;
+    if (typeof usage?.input_tokens === "number") acc.inputTokens = usage.input_tokens;
+    if (typeof usage?.cache_read_input_tokens === "number")
+      acc.cacheReadTokens = usage.cache_read_input_tokens;
+    if (typeof usage?.cache_creation_input_tokens === "number")
+      acc.cacheCreationTokens = usage.cache_creation_input_tokens;
+  }
+  if (c.type === "message_delta") {
+    const usage = c.usage;
+    const delta = c.delta;
+    if (typeof usage?.output_tokens === "number") acc.outputTokens = usage.output_tokens;
+    if (typeof delta?.stop_reason === "string") acc.finishReason = delta.stop_reason;
+  }
+}
+function isAsyncIterable(v) {
+  return typeof v === "object" && v !== null && Symbol.asyncIterator in v && typeof v[Symbol.asyncIterator] === "function";
+}
+function streamChunkText(chunk) {
+  if (!chunk || typeof chunk !== "object") return "";
+  const c = chunk;
+  if (Array.isArray(c.choices)) {
+    const choice = c.choices[0];
+    if (choice && typeof choice === "object") {
+      const delta = choice.delta;
+      if (delta && typeof delta === "object") {
+        const content = delta.content;
+        if (typeof content === "string") return content;
+      }
+    }
+  }
+  if (c.type === "content_block_delta") {
+    const delta = c.delta;
+    if (delta && typeof delta === "object") {
+      const d = delta;
+      if (d.type === "text_delta" && typeof d.text === "string") return d.text;
+    }
+  }
+  return "";
+}
+function wrapAsyncIterableForAssistantHook(stream, hook, provider, startTime) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      let content = "";
+      let firstChunkTime = -1;
+      let streamError;
+      const acc = {};
+      const accumChunkMeta = provider === "anthropic" ? accumAnthropicStreamChunkMeta : accumOpenAiStreamChunkMeta;
+      try {
+        for await (const chunk of stream) {
+          if (firstChunkTime === -1) firstChunkTime = Date.now();
+          content += streamChunkText(chunk);
+          accumChunkMeta(chunk, acc);
+          yield chunk;
+        }
+      } catch (err) {
+        streamError = err;
+        throw err;
+      } finally {
+        hook(content, {
+          ...acc,
+          httpStatus: streamError != null ? streamError.status ?? 500 : 200,
+          latencyMs: Date.now() - startTime,
+          timeToFirstTokenMs: firstChunkTime === -1 ? void 0 : firstChunkTime - startTime
+        });
+      }
+    }
+  };
+}
+function firstArgBodyStream(nextArgs) {
+  const body = nextArgs[0];
+  return !!(body && typeof body === "object" && body !== null && body.stream === true);
+}
+function extractAnthropicAssistantText(res) {
+  const content = res.content;
+  if (!Array.isArray(content)) return "";
+  let acc = "";
+  for (const item of content) {
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      const o = item;
+      if (o.type === "text" && typeof o.text === "string") {
+        acc += o.text;
+      }
+    }
+  }
+  return acc;
+}
+function extractOpenAiAssistantText(res) {
+  if (!Array.isArray(res.choices) || !res.choices[0] || typeof res.choices[0] !== "object") {
+    return "";
+  }
+  const message = res.choices[0].message;
+  return typeof message?.content === "string" ? message.content : "";
+}
+function isThenable(v) {
+  return !!v && (typeof v === "object" || typeof v === "function") && "then" in v && typeof v.then === "function";
+}
+function messageContentToText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  let acc = "";
+  for (const part of content) {
+    if (part && typeof part === "object" && !Array.isArray(part)) {
+      const p = part;
+      if (p.type === "text" && typeof p.text === "string") acc += p.text;
+    }
+  }
+  return acc;
+}
+function extractRecentMessages(nextArgs) {
+  const body = nextArgs[0];
+  if (!body || typeof body !== "object") return [];
+  const messages = body.messages;
+  if (!Array.isArray(messages)) return [];
+  const out = [];
+  for (const m of messages) {
+    if (!m || typeof m !== "object") continue;
+    const rec = m;
+    if (rec.role !== "user" && rec.role !== "assistant") continue;
+    const content = messageContentToText(rec.content).trim();
+    if (!content) continue;
+    out.push({ role: rec.role, content });
+  }
+  return out;
+}
+function extractTurnStartUserMessage(nextArgs) {
+  const body = nextArgs[0];
+  if (!body || typeof body !== "object") return void 0;
+  const messages = body.messages;
+  if (!Array.isArray(messages) || messages.length === 0) return void 0;
+  const last = messages[messages.length - 1];
+  if (!last || typeof last !== "object") return void 0;
+  const rec = last;
+  if (rec.role !== "user") return void 0;
+  const text = messageContentToText(rec.content).trim();
+  return text || void 0;
+}
+function withFirstflowBaggage(meta, fn) {
+  const base = propagation.getBaggage(context.active()) ?? propagation.createBaggage();
+  const bag = base.setEntry("firstflow.user_id", { value: meta.userId }).setEntry("firstflow.agent_id", { value: meta.agentId });
+  return context.with(propagation.setBaggage(context.active(), bag), fn);
+}
+function maybeObserveUserMessage(path, nextArgs, meta, ctx) {
+  if (!ctx.onUserMessage) return;
+  if (path !== "chat.completions.create" && path !== "messages.create") return;
+  if (!meta.conversationId) return;
+  const content = extractTurnStartUserMessage(nextArgs);
+  if (!content) return;
+  const recentMessages = extractRecentMessages(nextArgs);
+  ctx.onUserMessage({
+    agentId: meta.agentId,
+    conversationId: meta.conversationId,
+    userId: meta.userId,
+    role: "user",
+    content,
+    model: extractModel(nextArgs),
+    provider: detectProvider(path),
+    ...recentMessages.length ? { recentMessages } : {}
+  });
+}
+function maybeAttachAssistantHook(path, nextArgs, result, meta, ctx, startTime) {
+  if (!ctx.onAssistantComplete) return void 0;
+  if (path !== "chat.completions.create" && path !== "messages.create") {
+    return void 0;
+  }
+  const convId = meta.conversationId;
+  const recentMessages = extractRecentMessages(nextArgs);
+  const model = extractModel(nextArgs);
+  const provider = detectProvider(path);
+  const extractFull = path === "chat.completions.create" ? extractOpenAiAssistantText : extractAnthropicAssistantText;
+  const extractMeta = path === "chat.completions.create" ? extractOpenAiResponseMeta : extractAnthropicResponseMeta;
+  const emit = (content, llmMeta) => {
+    if (!convId) return;
+    ctx.onAssistantComplete?.({
+      agentId: meta.agentId,
+      conversationId: convId,
+      userId: meta.userId,
+      role: "assistant",
+      content,
+      model,
+      provider,
+      ...llmMeta,
+      ...recentMessages.length ? { recentMessages } : {}
+    });
+  };
+  if (firstArgBodyStream(nextArgs)) {
+    const wrapStream = (stream) => wrapAsyncIterableForAssistantHook(
+      stream,
+      (content, streamMeta) => emit(content, streamMeta),
+      provider,
+      startTime
+    );
+    if (isAsyncIterable(result)) {
+      return wrapStream(result);
+    }
+    if (isThenable(result)) {
+      return result.then(
+        (resolved) => isAsyncIterable(resolved) ? wrapStream(resolved) : resolved
+      );
+    }
+    return void 0;
+  }
+  if (isThenable(result)) {
+    return result.then((res) => {
+      const latencyMs = Date.now() - startTime;
+      const resMeta = extractMeta(res ?? {});
+      emit(extractFull(res ?? {}), { ...resMeta, latencyMs, httpStatus: 200 });
+      return res;
+    });
+  }
+  return void 0;
+}
+function wrapInstrumentedInvocation(path, original, thisArg, args, ctx) {
+  const parsed = parseFirstflowMeta(args);
+  const { meta } = parsed;
+  let nextArgs = parsed.nextArgs;
+  if (path === "chat.completions.create") {
+    nextArgs = injectOpenAiStreamUsage(nextArgs);
+  }
+  const startTime = Date.now();
+  const run = () => {
+    if (meta) maybeObserveUserMessage(path, nextArgs, meta, ctx);
+    let result;
+    try {
+      result = Reflect.apply(original, thisArg, nextArgs);
+    } catch (err) {
+      if (meta?.conversationId && ctx.onError) {
+        ctx.onError({
+          agentId: meta.agentId,
+          conversationId: meta.conversationId,
+          userId: meta.userId,
+          isError: true,
+          error: err instanceof Error ? err.message : String(err),
+          model: extractModel(nextArgs),
+          provider: detectProvider(path),
+          latencyMs: Date.now() - startTime,
+          httpStatus: err.status
+        });
+      }
+      throw err;
+    }
+    if (isThenable(result) && meta?.conversationId && ctx.onError) {
+      result = result.catch((err) => {
+        ctx.onError({
+          agentId: meta.agentId,
+          conversationId: meta.conversationId,
+          userId: meta.userId,
+          isError: true,
+          error: err instanceof Error ? err.message : String(err),
+          model: extractModel(nextArgs),
+          provider: detectProvider(path),
+          latencyMs: Date.now() - startTime,
+          httpStatus: err.status
+        });
+        return Promise.reject(err);
+      });
+    }
+    if (meta) {
+      const hooked = maybeAttachAssistantHook(path, nextArgs, result, meta, ctx, startTime);
+      if (hooked !== void 0) return hooked;
+    }
+    return result;
+  };
+  if (meta) {
+    return withFirstflowBaggage(meta, run);
+  }
+  return run();
+}
+function createNestedProxy(target, path, ctx) {
+  return new Proxy(target, {
+    get(_t, prop, receiver) {
+      const key = String(prop);
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        const joined = [...path, key].join(".");
+        return (...fnArgs) => {
+          if (INSTRUMENTED_PATHS.has(joined)) {
+            return wrapInstrumentedInvocation(
+              joined,
+              value,
+              target,
+              fnArgs,
+              ctx
+            );
+          }
+          return Reflect.apply(value, target, fnArgs);
+        };
+      }
+      if (value !== null && typeof value === "object") {
+        return createNestedProxy(value, [...path, key], ctx);
+      }
+      return value;
+    }
+  });
+}
+function wrapClient(client, ctx) {
+  return createNestedProxy(client, [], ctx);
+}
+
+export {
+  wrapClient
+};

package/dist/index.mjs

@@ -1,9 +1,11 @@
+import {
+  wrapClient
+} from "./chunk-WQZUOUMF.mjs";
 import {
   DEFAULT_FIRSTFLOW_BASE_URL,
   FIRSTFLOW_SERVER_PACKAGE_VERSION,
-  getRuntime,
-  wrapClient
-} from "./chunk-X3T7X4JQ.mjs";
+  getRuntime
+} from "./chunk-QBEGXT76.mjs";
 
 // src/standalone.ts
 function observe(input) {

package/dist/langchain.d.mts

@@ -0,0 +1,56 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+
+/** The three identifiers every observed turn is attributed to. */
+type FirstflowIdentity = {
+    /** Agent this run is attributed to (primary routing key). */
+    agentId: string;
+    /** Session / conversation / thread id (groups messages in Sessions). */
+    sessionId: string;
+    /** The end-user this run belongs to (stable across sessions). */
+    userId: string;
+};
+type Rec = Record<string, unknown>;
+/**
+ * LangChain callback handler that forwards each model turn to Firstflow
+ * (Sessions + Analytics), tagged from the run `metadata`. Attach it via
+ * `callbacks: [handler]` and pass `metadata: { firstflowAgentId, sessionId,
+ * userId }`, or use {@link withFirstflow} to do both at once.
+ *
+ * Stateless apart from a short-lived per-run map; one shared instance is safe to
+ * reuse across the whole process (see {@link firstflowCallback}).
+ */
+declare class FirstflowCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private readonly runs;
+    handleChatModelStart(_llm: unknown, messages: unknown, runId: string, _parentRunId?: string, extraParams?: Rec, _tags?: string[], metadata?: Rec): void;
+    handleLLMStart(_llm: unknown, prompts: unknown, runId: string, _parentRunId?: string, extraParams?: Rec, _tags?: string[], metadata?: Rec): void;
+    private begin;
+    handleLLMNewToken(_token: string, _idx: unknown, runId: string): void;
+    handleLLMEnd(output: unknown, runId: string): void;
+    handleLLMError(err: unknown, runId: string): void;
+}
+/**
+ * The process-wide shared handler. Prefer this over allocating a new handler per
+ * call — it is safe to reuse everywhere.
+ */
+declare function firstflowCallback(): FirstflowCallbackHandler;
+/** A minimal LangChain run-config shape (avoids a hard type dep on the peer). */
+type RunnableConfigLike = {
+    callbacks?: unknown;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Merge the Firstflow handler + identity metadata into a LangChain run config.
+ * Pass the result as the second arg to `invoke` / `stream` / `graph.stream`:
+ *
+ *   await graph.stream(state, withFirstflow({ agentId, sessionId, userId }));
+ *
+ * Existing array callbacks and metadata are preserved.
+ */
+declare function withFirstflow<T extends RunnableConfigLike>(identity: FirstflowIdentity, config?: T): T & {
+    callbacks: unknown[];
+    metadata: Record<string, unknown>;
+};
+
+export { FirstflowCallbackHandler, type FirstflowIdentity, firstflowCallback, withFirstflow };

package/dist/langchain.d.ts

@@ -0,0 +1,56 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+
+/** The three identifiers every observed turn is attributed to. */
+type FirstflowIdentity = {
+    /** Agent this run is attributed to (primary routing key). */
+    agentId: string;
+    /** Session / conversation / thread id (groups messages in Sessions). */
+    sessionId: string;
+    /** The end-user this run belongs to (stable across sessions). */
+    userId: string;
+};
+type Rec = Record<string, unknown>;
+/**
+ * LangChain callback handler that forwards each model turn to Firstflow
+ * (Sessions + Analytics), tagged from the run `metadata`. Attach it via
+ * `callbacks: [handler]` and pass `metadata: { firstflowAgentId, sessionId,
+ * userId }`, or use {@link withFirstflow} to do both at once.
+ *
+ * Stateless apart from a short-lived per-run map; one shared instance is safe to
+ * reuse across the whole process (see {@link firstflowCallback}).
+ */
+declare class FirstflowCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private readonly runs;
+    handleChatModelStart(_llm: unknown, messages: unknown, runId: string, _parentRunId?: string, extraParams?: Rec, _tags?: string[], metadata?: Rec): void;
+    handleLLMStart(_llm: unknown, prompts: unknown, runId: string, _parentRunId?: string, extraParams?: Rec, _tags?: string[], metadata?: Rec): void;
+    private begin;
+    handleLLMNewToken(_token: string, _idx: unknown, runId: string): void;
+    handleLLMEnd(output: unknown, runId: string): void;
+    handleLLMError(err: unknown, runId: string): void;
+}
+/**
+ * The process-wide shared handler. Prefer this over allocating a new handler per
+ * call — it is safe to reuse everywhere.
+ */
+declare function firstflowCallback(): FirstflowCallbackHandler;
+/** A minimal LangChain run-config shape (avoids a hard type dep on the peer). */
+type RunnableConfigLike = {
+    callbacks?: unknown;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Merge the Firstflow handler + identity metadata into a LangChain run config.
+ * Pass the result as the second arg to `invoke` / `stream` / `graph.stream`:
+ *
+ *   await graph.stream(state, withFirstflow({ agentId, sessionId, userId }));
+ *
+ * Existing array callbacks and metadata are preserved.
+ */
+declare function withFirstflow<T extends RunnableConfigLike>(identity: FirstflowIdentity, config?: T): T & {
+    callbacks: unknown[];
+    metadata: Record<string, unknown>;
+};
+
+export { FirstflowCallbackHandler, type FirstflowIdentity, firstflowCallback, withFirstflow };