Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(interact): add langsmith grouped by browser session (#3357)
Developers Digestdb6f9cf24dac
diff --git a/apps/api/package.json b/apps/api/package.jsonindex 578dbe2a9..0841e65a9 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -122,6 +122,7 @@"joplin-turndown-plugin-gfm": "^1.0.12","jsdom": "^26.0.0","koffi": "^2.9.0",+ "langsmith": "^0.5.18","lodash": "^4.18.0","marked": "^14.1.2","ollama-ai-provider": "^1.2.0",diff --git a/apps/api/pnpm-lock.yaml b/apps/api/pnpm-lock.yamlindex f3617406a..9a0848db7 100644--- a/apps/api/pnpm-lock.yaml+++ b/apps/api/pnpm-lock.yaml@@ -177,6 +177,9 @@ importers:koffi:specifier: ^2.9.0version: 2.9.0+ langsmith:+ specifier: ^0.5.18+ version: 0.5.18(@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected]))([email protected]([email protected]([email protected])([email protected]))([email protected]))([email protected]([email protected])([email protected]))lodash:specifier: ^4.18.0version: 4.18.1@@ -3676,6 +3679,9 @@ packages:resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}engines: {node: '>=6'}+ resolution: {integrity: sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==}+resolution: {integrity: sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==}@@ -4414,6 +4420,26 @@ packages:resolution: {integrity: sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A==}+ resolution: {integrity: sha512-3zuZUWffTHQ+73EAwnodADtf534VNEZUpXr9jC12qyG8/IQuJET7PRsCpTb9wX2lmBspakwLUpqpj3tNm/0bVA==}+ peerDependencies:+ '@opentelemetry/api': '*'+ '@opentelemetry/exporter-trace-otlp-proto': '*'+ '@opentelemetry/sdk-trace-base': '*'+ openai: '*'+ ws: '>=7'+ peerDependenciesMeta:+ '@opentelemetry/api':+ optional: true+ '@opentelemetry/exporter-trace-otlp-proto':+ optional: true+ '@opentelemetry/sdk-trace-base':+ optional: true+ openai:+ optional: true+ ws:+ optional: true+resolution: {integrity: sha512-y+SqErxb8h7nE/fiEX07jsbuhrpO9lL8eca7/Y1nuWV2moNlXhyd59iDGcRf6moVyDMbmTNzL40SUyrFU/yDpg==}@@ -4791,6 +4817,10 @@ packages:oxlint-tsgolint:optional: true+ resolution: {integrity: sha512-LICb2p9CB7FS+0eR1oqWnHhp0FljGLZCWBE9aix0Uye9W8LTQPwMTYVGWQWIw9RdQiDg4+epXQODwIYJtSJaow==}+ engines: {node: '>=4'}+resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}engines: {node: '>=6'}@@ -4803,6 +4833,14 @@ packages:resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}engines: {node: '>=8'}+ resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==}+ engines: {node: '>=8'}++ resolution: {integrity: sha512-rhIwUycgwwKcP9yTOOFK/AKsAopjjCakVqLHePO3CC6Mir1Z99xT+R63jZxAT5lFZLa2inS5h+ZS2GvR99/FBg==}+ engines: {node: '>=8'}+resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}engines: {node: '>=6'}@@ -5620,6 +5658,10 @@ packages:resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}engines: {node: '>= 0.4.0'}+ resolution: {integrity: sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==}+ hasBin: true+resolution: {integrity: sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==}hasBin: true@@ -9312,6 +9354,8 @@ snapshots:+ [email protected]: {}+@@ -10405,6 +10449,16 @@ snapshots:+ [email protected](@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected]))([email protected]([email protected]([email protected])([email protected]))([email protected]))([email protected]([email protected])([email protected])):+ dependencies:+ p-queue: 6.6.2+ uuid: 10.0.0+ optionalDependencies:+ '@opentelemetry/api': 1.9.0+ '@opentelemetry/sdk-trace-base': 2.2.0(@opentelemetry/[email protected])+ ws: 8.18.0([email protected])([email protected])+@@ -10759,6 +10813,8 @@ snapshots:'@oxlint/win32-arm64': 1.14.0'@oxlint/win32-x64': 1.14.0+ [email protected]: {}+dependencies:p-try: 2.2.0@@ -10771,6 +10827,15 @@ snapshots:dependencies:p-limit: 2.3.0+ dependencies:+ eventemitter3: 4.0.7+ p-timeout: 3.2.0++ dependencies:+ p-finally: 1.0.0+@@ -11583,6 +11648,8 @@ snapshots:+ [email protected]: {}+diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex 7caea74cd..adf824efd 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -203,6 +203,12 @@ const configSchema = z.object({OLLAMA_BASE_URL: z.string().optional(),VERTEX_CREDENTIALS: z.string().optional(),+ // LangSmith (tracing for interact agent)+ LANGSMITH_API_KEY: z.string().optional(),+ LANGSMITH_PROJECT: z.string().optional(),+ LANGSMITH_ENDPOINT: z.string().optional(),+ LANGSMITH_TRACING: z.stringbool().optional(),+// Rate LimitingRATE_LIMIT_TEST_API_KEY_SCRAPE: z.coerce.number().optional(),RATE_LIMIT_TEST_API_KEY_CRAWL: z.coerce.number().optional(),diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.tsindex 3ace5ac03..fc8e11cfc 100644--- a/apps/api/src/controllers/v2/scrape-browser.ts+++ b/apps/api/src/controllers/v2/scrape-browser.ts@@ -37,8 +37,11 @@ import {} from "../../lib/scrape-interact/scrape-replay";import {executePromptViaBrowserAgent,+ executeCodeViaBrowserSession,AgentResult,} from "../../lib/scrape-interact/browser-agent";+import { sanitizeUrlForTrace } from "../../lib/scrape-interact/langsmith";+import { getScrapeZDR } from "../../lib/zdr-helpers";import { RequestWithAuth, ScrapeOptions } from "./types";import { billTeam } from "../../services/billing/credit_billing";import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";@@ -217,6 +220,36 @@ export async function scrapeInteractController(updateBrowserSessionActivity(session.id).catch(() => {});// --- Execute: prompt-based agent loop OR direct code ---+ //+ // Skip LangSmith tracing entirely for teams with forced zero-data-retention,+ // matching how tracking.ts skips ClickHouse writes. The trace would otherwise+ // ship the full prompt, tool I/O, and page snapshots to a third party.+ const zdrForced = getScrapeZDR(req.acuc?.flags) === "forced";++ // Upstream context from the scrape job β interact extends scrape, so+ // every run carries the URL / wait / actions / origin that set the stage+ // for what the agent does on top of it. URLs are stripped of query+ // strings to avoid leaking PII into LangSmith.+ const scrapeOptions = (scrape.options ?? {}) as {+ origin?: string;+ };+ const traceScrapeContext = {+ scrapeUrl: sanitizeUrlForTrace(scrape.url),+ targetUrl: sanitizeUrlForTrace(replayContext.targetUrl),+ scrapeWaitForMs: replayContext.waitForMs,+ scrapeActions: replayContext.actions.length,+ scrapeOrigin:+ typeof scrapeOptions.origin === "string"+ ? scrapeOptions.origin+ : undefined,+ };++ // Identity fields below team_id β optional, normalized from null β undefined+ // so LangSmith metadata filters don't match empty strings.+ const traceIdentity = {+ orgId: req.auth.org_id ?? undefined,+ subUserId: req.acuc?.sub_user_id ?? undefined,+ };let execResult: BrowserServiceExecResponse | AgentResult;@@ -231,6 +264,14 @@ export async function scrapeInteractController(session.browser_id,timeout,logger,+ {+ sessionId: session.id,+ scrapeId,+ teamId: req.auth.team_id,+ ...traceIdentity,+ zeroDataRetention: zdrForced,+ ...traceScrapeContext,+ },);} catch (err) {logger.error("Agent loop failed", { error: err });@@ -253,10 +294,17 @@ export async function scrapeInteractController(logger.info("Executing code in browser session", { language, timeout });try {- execResult = await browserServiceRequest<BrowserServiceExecResponse>(- "POST",- `/browsers/${session.browser_id}/exec`,+ execResult = await executeCodeViaBrowserSession(+ session.browser_id,{ code: rawCode!, language, timeout, origin },+ {+ sessionId: session.id,+ scrapeId,+ teamId: req.auth.team_id,+ ...traceIdentity,+ zeroDataRetention: zdrForced,+ ...traceScrapeContext,+ },);} catch (err) {logger.error("Failed to execute code via browser service", {diff --git a/apps/api/src/lib/scrape-interact/browser-agent.ts b/apps/api/src/lib/scrape-interact/browser-agent.tsindex bb4003276..32ed7f1a4 100644--- a/apps/api/src/lib/scrape-interact/browser-agent.ts+++ b/apps/api/src/lib/scrape-interact/browser-agent.ts@@ -1,7 +1,7 @@import { z } from "zod";import { promises as fs } from "fs";import path from "path";-import { generateText, tool, stepCountIs } from "ai";+import { tool, stepCountIs } from "ai";import { logger as _logger } from "../logger";import { getModel } from "../generic-ai";import {@@ -9,6 +9,12 @@ import {BrowserServiceExecResponse,} from "./browser-service-client";import { config } from "../../config";+import {+ generateText,+ buildLangSmithProviderOptions,+ traceInteract,+ InteractTraceMetadata,+} from "./langsmith";// ---------------------------------------------------------------------------// Constants@@ -179,11 +185,26 @@ async function takeSnapshot(browserId: string): Promise<string> {// Main agent β tool-calling loop via AI SDK// ---------------------------------------------------------------------------+export interface BrowserAgentTraceContext {+ sessionId: string;+ scrapeId: string;+ teamId: string;+ orgId?: string;+ subUserId?: string;+ zeroDataRetention?: boolean;+ scrapeUrl?: string;+ targetUrl?: string;+ scrapeWaitForMs?: number;+ scrapeActions?: number;+ scrapeOrigin?: string;+}+export async function executePromptViaBrowserAgent(prompt: string,browserId: string,stepTimeout: number,logger: typeof _logger,+ trace?: BrowserAgentTraceContext,): Promise<AgentResult> {const debugLog = new AgentDebugLog(browserId);debugLog.add(`=== AGENT RUN ===`);@@ -293,6 +314,31 @@ export async function executePromptViaBrowserAgent(},});+ const langsmith = trace+ ? buildLangSmithProviderOptions(+ {+ thread_id: trace.sessionId,+ session_id: trace.sessionId,+ scrape_id: trace.scrapeId,+ team_id: trace.teamId,+ org_id: trace.orgId,+ sub_user_id: trace.subUserId,+ browser_id: browserId,+ mode: "prompt",+ zeroDataRetention: trace.zeroDataRetention,+ scrape_url: trace.scrapeUrl,+ target_url: trace.targetUrl,+ scrape_wait_for_ms: trace.scrapeWaitForMs,+ scrape_actions: trace.scrapeActions,+ scrape_origin: trace.scrapeOrigin,+ } satisfies InteractTraceMetadata,+ {+ name: "interact:prompt",+ extra: { prompt_length: prompt.length },+ },+ )+ : undefined;+try {const result = await generateText({model: getModel("gemini-2.5-flash", "google"),@@ -311,6 +357,12 @@ export async function executePromptViaBrowserAgent(tools: { browser: browserTool },stopWhen: stepCountIs(MAX_STEPS),temperature: 0,+ // LangSmith's provider-options object is recognized by wrapAISDK but+ // does not satisfy AI SDK's SharedV3ProviderOptions shape, hence the+ // local cast β keeps the rest of the type surface strict.+ ...(langsmith+ ? { providerOptions: { langsmith } as Record<string, any> }+ : {}),prepareStep: async ({ stepNumber, messages }) => {if (actionLog.length === 0) return {};return {@@ -363,3 +415,54 @@ export async function executePromptViaBrowserAgent(};}}++// ---------------------------------------------------------------------------+// Code path β direct exec wrapped with the same trace metadata shape as the+// prompt path, so tracing details don't have to live in the controller.+// ---------------------------------------------------------------------------++export async function executeCodeViaBrowserSession(+ browserId: string,+ params: {+ code: string;+ language: string;+ timeout: number;+ origin?: string;+ },+ trace?: BrowserAgentTraceContext,+): Promise<BrowserServiceExecResponse> {+ // Arg must be named so langsmith's traceable sees the exec params as the+ // run's `inputs`; a zero-arg closure would record `{}` and strip the code,+ // language, timeout, and origin from every trace.+ const run = async (execParams: typeof params) =>+ browserServiceRequest<BrowserServiceExecResponse>(+ "POST",+ `/browsers/${browserId}/exec`,+ execParams,+ );++ if (!trace) return run(params);++ const traced = traceInteract(+ run,+ {+ thread_id: trace.sessionId,+ session_id: trace.sessionId,+ scrape_id: trace.scrapeId,+ team_id: trace.teamId,+ org_id: trace.orgId,+ sub_user_id: trace.subUserId,+ browser_id: browserId,+ mode: "code",+ zeroDataRetention: trace.zeroDataRetention,+ scrape_url: trace.scrapeUrl,+ target_url: trace.targetUrl,+ scrape_wait_for_ms: trace.scrapeWaitForMs,+ scrape_actions: trace.scrapeActions,+ scrape_origin: trace.scrapeOrigin,+ } satisfies InteractTraceMetadata,+ { name: "interact:code" },+ );++ return traced(params);+}diff --git a/apps/api/src/lib/scrape-interact/langsmith.test.ts b/apps/api/src/lib/scrape-interact/langsmith.test.tsnew file mode 100644index 000000000..33d64e288--- /dev/null+++ b/apps/api/src/lib/scrape-interact/langsmith.test.ts@@ -0,0 +1,307 @@+/**+ * Sanity tests for the LangSmith wiring. The disabled-path block isolates+ * modules and strips LANGSMITH_* env vars so the tests don't depend on the+ * developer's local .env, where LANGSMITH_API_KEY may or may not be set.+ */+import * as ai from "ai";++describe("scrape-interact/langsmith (disabled β no API key)", () => {+ beforeEach(() => {+ jest.resetModules();+ // Mock config to ensure LANGSMITH_API_KEY is unset regardless of what's+ // in the developer's local .env file β this keeps the disabled-path+ // tests hermetic.+ jest.doMock("../../config", () => ({+ config: {+ LANGSMITH_API_KEY: undefined,+ LANGSMITH_TRACING: undefined,+ LANGSMITH_PROJECT: undefined,+ LANGSMITH_ENDPOINT: undefined,+ },+ }));+ });++ afterEach(() => {+ jest.dontMock("../../config");+ });++ it("reports disabled when LANGSMITH_API_KEY is unset", () => {+ const mod = require("./langsmith");+ expect(mod.isLangSmithEnabled).toBe(false);+ });++ it("re-exports raw ai SDK functions when disabled", () => {+ const freshAi = require("ai");+ const mod = require("./langsmith");+ expect(mod.generateText).toBe(freshAi.generateText);+ expect(mod.streamText).toBe(freshAi.streamText);+ expect(mod.generateObject).toBe(freshAi.generateObject);+ expect(mod.streamObject).toBe(freshAi.streamObject);+ });++ it("returns undefined providerOptions when disabled", () => {+ const mod = require("./langsmith");+ const opts = mod.buildLangSmithProviderOptions(+ {+ thread_id: "t1",+ session_id: "t1",+ scrape_id: "s1",+ team_id: "team1",+ mode: "prompt",+ },+ { name: "test" },+ );+ expect(opts).toBeUndefined();+ });++ it("traceInteract returns the original function unchanged when disabled", async () => {+ const mod = require("./langsmith");+ const original = async (x: number) => x * 2;+ const wrapped = mod.traceInteract(+ original,+ {+ thread_id: "t1",+ session_id: "t1",+ scrape_id: "s1",+ team_id: "team1",+ mode: "code",+ },+ { name: "test" },+ );+ expect(wrapped).toBe(original);+ await expect(wrapped(3)).resolves.toBe(6);+ });++ it("treats an API key alone (no LANGSMITH_TRACING) as disabled", () => {+ jest.resetModules();+ jest.doMock("../../config", () => ({+ config: {+ LANGSMITH_API_KEY: "real-looking-key",+ LANGSMITH_TRACING: undefined,+ LANGSMITH_PROJECT: undefined,+ LANGSMITH_ENDPOINT: undefined,+ },+ }));+ const mod = require("./langsmith");+ expect(mod.isLangSmithEnabled).toBe(false);+ });++ it("treats whitespace-only LANGSMITH_API_KEY as disabled", () => {+ jest.resetModules();+ jest.doMock("../../config", () => ({+ config: {+ LANGSMITH_API_KEY: " \t\n ",+ LANGSMITH_TRACING: true,+ LANGSMITH_PROJECT: undefined,+ LANGSMITH_ENDPOINT: undefined,+ },+ }));+ const mod = require("./langsmith");+ expect(mod.isLangSmithEnabled).toBe(false);+ });++ it("sanitizeUrlForTrace strips query strings and fragments", () => {+ const { sanitizeUrlForTrace } = require("./langsmith");+ expect(sanitizeUrlForTrace("https://example.com/page?token=abc#x")).toBe(+ "https://example.com/page",+ );+ expect(sanitizeUrlForTrace("https://example.com/")).toBe(+ "https://example.com/",+ );+ expect(sanitizeUrlForTrace(null)).toBeUndefined();+ expect(sanitizeUrlForTrace(undefined)).toBeUndefined();+ // Malformed URL still gets query/fragment stripped+ expect(sanitizeUrlForTrace("not a url?token=secret#frag")).toBe(+ "not a url",+ );+ expect(sanitizeUrlForTrace("not a url")).toBe("not a url");+ });+});++describe("scrape-interact/langsmith (enabled β mocked SDK)", () => {+ // These tests reset module state and provide fake langsmith modules so we+ // can exercise the wrap path without network calls or a real API key.++ const ORIGINAL_ENV = { ...process.env };+ const fakeWrappedFns = {+ generateText: jest.fn(),+ streamText: jest.fn(),+ generateObject: jest.fn(),+ streamObject: jest.fn(),+ };+ const createProviderOptionsSpy = jest.fn((opts: unknown) => ({+ __fake_langsmith_options__: true,+ payload: opts,+ }));+ const traceableSpy = jest.fn(+ (fn: (...args: unknown[]) => unknown, _opts: unknown) => {+ const wrapper = (...args: unknown[]) => fn(...args);+ (+ wrapper as unknown as { __fake_traceable__: boolean }+ ).__fake_traceable__ = true;+ return wrapper;+ },+ );++ beforeEach(() => {+ jest.resetModules();+ createProviderOptionsSpy.mockClear();+ traceableSpy.mockClear();+ // Mock config with only the fields the module reads so the test is+ // hermetic β it doesn't depend on the developer's local .env making it+ // through the zod schema at require time.+ jest.doMock("../../config", () => ({+ config: {+ LANGSMITH_API_KEY: "test-fake-key",+ LANGSMITH_TRACING: true,+ LANGSMITH_PROJECT: "test-project",+ LANGSMITH_ENDPOINT: undefined,+ },+ }));+ jest.doMock("langsmith/experimental/vercel", () => ({+ wrapAISDK: () => fakeWrappedFns,+ createLangSmithProviderOptions: createProviderOptionsSpy,+ }));+ jest.doMock("langsmith/traceable", () => ({+ traceable: traceableSpy,+ }));+ });++ afterEach(() => {+ process.env = { ...ORIGINAL_ENV };+ jest.dontMock("../../config");+ jest.dontMock("langsmith/experimental/vercel");+ jest.dontMock("langsmith/traceable");+ });++ it("reports enabled and swaps generateText for the wrapped fn", () => {+ const mod = require("./langsmith");+ expect(mod.isLangSmithEnabled).toBe(true);+ expect(mod.generateText).toBe(fakeWrappedFns.generateText);+ expect(mod.generateText).not.toBe(ai.generateText);+ });++ it("builds provider options with thread_id + scrape context metadata", () => {+ const mod = require("./langsmith");+ const result = mod.buildLangSmithProviderOptions(+ {+ thread_id: "sess-abc",+ session_id: "sess-abc",+ scrape_id: "scrape-xyz",+ team_id: "team-42",+ browser_id: "browser-1",+ mode: "prompt",+ scrape_url: "https://example.com/pricing",+ target_url: "https://example.com/pricing/",+ scrape_wait_for_ms: 500,+ scrape_actions: 2,+ scrape_origin: "api",+ },+ { name: "interact:prompt", extra: { prompt_length: 123 } },+ );++ expect(createProviderOptionsSpy).toHaveBeenCalledTimes(1);+ const callArg = createProviderOptionsSpy.mock.calls[0][0] as {+ name: string;+ metadata: Record<string, unknown>;+ tags: string[];+ };+ expect(callArg.name).toBe("interact:prompt");+ expect(callArg.metadata).toMatchObject({+ thread_id: "sess-abc",+ session_id: "sess-abc",+ scrape_id: "scrape-xyz",+ team_id: "team-42",+ scrape_url: "https://example.com/pricing",+ target_url: "https://example.com/pricing/",+ scrape_wait_for_ms: 500,+ scrape_actions: 2,+ scrape_origin: "api",+ browser_id: "browser-1",+ mode: "prompt",+ prompt_length: 123,+ });+ expect(callArg.tags).toEqual(["interact", "mode:prompt"]);+ expect(result).toMatchObject({ __fake_langsmith_options__: true });+ });++ it("skips tracing when meta.zeroDataRetention is true", () => {+ const mod = require("./langsmith");+ const result = mod.buildLangSmithProviderOptions({+ thread_id: "sess-abc",+ session_id: "sess-abc",+ scrape_id: "scrape-xyz",+ team_id: "team-42",+ mode: "prompt",+ zeroDataRetention: true,+ });+ expect(result).toBeUndefined();+ expect(createProviderOptionsSpy).not.toHaveBeenCalled();++ const fn = async () => "should-still-run";+ const wrapped = mod.traceInteract(fn, {+ thread_id: "sess-abc",+ session_id: "sess-abc",+ scrape_id: "scrape-xyz",+ team_id: "team-42",+ mode: "code",+ zeroDataRetention: true,+ });+ expect(wrapped).toBe(fn);+ expect(traceableSpy).not.toHaveBeenCalled();+ });++ it("wraps functions via traceable when zeroDataRetention is not set", async () => {+ const mod = require("./langsmith");+ const fn = jest.fn(async (x: number) => x + 1);+ const wrapped = mod.traceInteract(+ fn,+ {+ thread_id: "sess-abc",+ session_id: "sess-abc",+ scrape_id: "scrape-xyz",+ team_id: "team-42",+ mode: "code",+ },+ { name: "interact:code" },+ );+ expect(traceableSpy).toHaveBeenCalledTimes(1);+ const traceableOpts = traceableSpy.mock.calls[0][1] as {+ name: string;+ run_type: string;+ metadata: Record<string, unknown>;+ tags: string[];+ };+ expect(traceableOpts.name).toBe("interact:code");+ expect(traceableOpts.run_type).toBe("chain");+ expect(traceableOpts.tags).toEqual(["interact", "mode:code"]);+ expect(traceableOpts.metadata).toMatchObject({+ thread_id: "sess-abc",+ mode: "code",+ });+ await expect(wrapped(5)).resolves.toBe(6);+ expect(fn).toHaveBeenCalledWith(5);+ });++ it("falls back to raw ai SDK when langsmith require() throws", () => {+ jest.resetModules();+ jest.doMock("langsmith/experimental/vercel", () => {+ throw new Error("simulated install breakage");+ });+ jest.doMock("langsmith/traceable", () => ({ traceable: traceableSpy }));+ // Re-require ai from the fresh module graph so the identity check lines up+ // with the module instance the langsmith helper imported.+ const freshAi = require("ai");+ const mod = require("./langsmith");+ expect(mod.generateText).toBe(freshAi.generateText);+ expect(+ mod.buildLangSmithProviderOptions({+ thread_id: "t",+ session_id: "t",+ scrape_id: "s",+ team_id: "x",+ mode: "prompt",+ }),+ ).toBeUndefined();+ });+});diff --git a/apps/api/src/lib/scrape-interact/langsmith.ts b/apps/api/src/lib/scrape-interact/langsmith.tsnew file mode 100644index 000000000..35be34137--- /dev/null+++ b/apps/api/src/lib/scrape-interact/langsmith.ts@@ -0,0 +1,178 @@+import * as ai from "ai";+import { config } from "../../config";+import { logger as _logger } from "../logger";++const logger = _logger.child({ module: "scrape-interact/langsmith" });++// Trim once at module load β a whitespace-only LANGSMITH_API_KEY would be+// truthy in JS, flip the gate on, and then every trace POST would silently+// 401 against LangSmith with no other signal that something's wrong.+const LANGSMITH_API_KEY = config.LANGSMITH_API_KEY?.trim() || undefined;++// Opt-in: require both a key AND explicit LANGSMITH_TRACING=true. Having a+// key alone shouldn't start shipping traces, since operators may set the key+// for local experimentation and be surprised when prod starts tracing too.+export const isLangSmithEnabled = Boolean(+ LANGSMITH_API_KEY && config.LANGSMITH_TRACING === true,+);++export type InteractTraceMetadata = {+ thread_id: string;+ session_id: string;+ scrape_id: string;+ team_id: string;+ // Optional identifiers below team_id for finer-grained LangSmith filtering.+ // sub_user_id is the per-request sub-user label (when the API key carries+ // one); org_id is the parent org when teams are grouped. Neither is always+ // present β team_id is the only guaranteed identity.+ org_id?: string;+ sub_user_id?: string;+ browser_id?: string;+ run_id?: string;+ mode: "prompt" | "code";+ // Context inherited from the upstream scrape that this interact session is+ // continuing. Interact extends scrape, so the agent's work only makes sense+ // alongside what the scrape set up: the target URL, how long it waited,+ // what pre-actions ran, and where the scrape was initiated. URLs are+ // normalized to origin+path (no query string) before being attached to+ // avoid leaking query-string PII into LangSmith.+ scrape_url?: string;+ target_url?: string;+ scrape_wait_for_ms?: number;+ scrape_actions?: number;+ scrape_origin?: string;+ // When true, the caller has determined the team/scrape is under+ // zero-data-retention and tracing must be skipped entirely so no prompt,+ // code, or tool I/O is shipped to LangSmith.+ zeroDataRetention?: boolean;+};++/**+ * Strip query string + fragment from a URL so it can safely go into trace+ * metadata. A plain split is used rather than `new URL()` so malformed inputs+ * can't slip through a `catch` branch still carrying `?token=...` fragments.+ */+export function sanitizeUrlForTrace(+ url: string | null | undefined,+): string | undefined {+ if (!url) return undefined;+ return url.split("?")[0].split("#")[0];+}++type WrappedAISDK = {+ generateText: typeof ai.generateText;+ streamText: typeof ai.streamText;+ generateObject: typeof ai.generateObject;+ streamObject: typeof ai.streamObject;+};++type LangSmithProviderOptions = {+ name?: string;+ metadata?: Record<string, unknown>;+ tags?: string[];+};++type TraceableOptions = {+ name?: string;+ run_type?:+ | "tool"+ | "chain"+ | "llm"+ | "retriever"+ | "embedding"+ | "prompt"+ | "parser";+ metadata?: Record<string, unknown>;+ tags?: string[];+};++type LangSmithProviderOptionsReturn = Record<string, unknown>;++let wrappedSDK: WrappedAISDK = ai;+let createLangSmithProviderOptionsFn:+ | ((opts: LangSmithProviderOptions) => LangSmithProviderOptionsReturn)+ | null = null;+let traceableFn:+ | (<F extends (...args: any[]) => any>(fn: F, opts?: TraceableOptions) => F)+ | null = null;++if (isLangSmithEnabled) {+ try {+ const vercelWrapper = require("langsmith/experimental/vercel");+ const traceableMod = require("langsmith/traceable");+ wrappedSDK = vercelWrapper.wrapAISDK(ai);+ createLangSmithProviderOptionsFn =+ vercelWrapper.createLangSmithProviderOptions;+ traceableFn = traceableMod.traceable;++ // Mirror our config into process.env only after the langsmith modules+ // loaded successfully. If init fails we fall back to the raw ai SDK+ // without polluting the process env for other modules. Use the trimmed+ // key so whitespace padding in .env can't reach the langsmith SDK.+ process.env.LANGSMITH_TRACING = "true";+ process.env.LANGSMITH_API_KEY = LANGSMITH_API_KEY!;+ if (config.LANGSMITH_PROJECT) {+ process.env.LANGSMITH_PROJECT = config.LANGSMITH_PROJECT;+ }+ if (config.LANGSMITH_ENDPOINT) {+ process.env.LANGSMITH_ENDPOINT = config.LANGSMITH_ENDPOINT;+ }++ logger.info("LangSmith tracing enabled for interact agent", {+ project: config.LANGSMITH_PROJECT ?? "(default)",+ });+ } catch (err) {+ logger.error(+ "Failed to initialize LangSmith β falling back to raw ai SDK",+ {+ error: err,+ },+ );+ }+}++export const { generateText, streamText, generateObject, streamObject } =+ wrappedSDK;++// The LangSmith provider config is recognized by wrapAISDK but is not a+// first-class AI SDK provider, so callers still need a narrow cast when+// assigning to AI SDK's typed `providerOptions`. We keep the helper's return+// type honest so the cast is local to the call site rather than `any`+// propagating back here.+export function buildLangSmithProviderOptions(+ meta: InteractTraceMetadata,+ opts: {+ name?: string;+ tags?: string[];+ extra?: Record<string, unknown>;+ } = {},+): LangSmithProviderOptionsReturn | undefined {+ if (+ !isLangSmithEnabled ||+ !createLangSmithProviderOptionsFn ||+ meta.zeroDataRetention+ ) {+ return undefined;+ }++ return createLangSmithProviderOptionsFn({+ name: opts.name,+ metadata: { ...meta, ...(opts.extra ?? {}) },+ tags: ["interact", `mode:${meta.mode}`, ...(opts.tags ?? [])],+ });+}++export function traceInteract<F extends (...args: any[]) => any>(+ fn: F,+ meta: InteractTraceMetadata,+ opts: { name?: string; runType?: TraceableOptions["run_type"] } = {},+): F {+ if (!isLangSmithEnabled || !traceableFn || meta.zeroDataRetention) return fn;++ return traceableFn(fn, {+ name: opts.name ?? `interact:${meta.mode}`,+ run_type: opts.runType ?? "chain",+ metadata: { ...meta },+ tags: ["interact", `mode:${meta.mode}`],+ });+}