@librechat/agents 3.2.68 → 3.3.0

package/src/run.ts

@@ -1,9 +1,9 @@
 // src/run.ts
-import { HumanMessage } from '@langchain/core/messages';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import {
   Command,
   INTERRUPT,
@@ -26,10 +26,19 @@ import {
   isLangfuseCallbackHandler,
   withLangfuseAttributes,
 } from '@/langfuse';
+import {
+  hasToolOutputTracingConfig,
+  resolveLangfuseConfig,
+  resolveToolOutputTracingConfig,
+} from '@/langfuseConfig';
 import {
   resolveLangfuseRuntimeScope,
   withLangfuseRuntimeScope,
 } from '@/langfuseRuntimeScope';
+import {
+  ACTIVITY_LABEL_PROMPT,
+  buildActivityLabelPrompt,
+} from '@/prompts/activityLabel';
 import {
   appendCallbacks,
   findCallback,
@@ -43,7 +52,7 @@ import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { initializeLangfuseTracing } from './instrumentation';
 import { GraphEvents, Callback, TitleMethod } from '@/common';
 import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
-import { resolveLangfuseConfig } from '@/langfuseConfig';
+import { getTraceIdSeed } from '@/langfuseRuntimeContext';
 import { StandardGraph } from '@/graphs/Graph';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
@@ -153,6 +162,8 @@ export class Run<_T extends t.BaseGraphState> {
    * lets callers assert the type they expect.
    */
   private _interrupt: t.RunInterruptResult<unknown> | undefined;
+  /** Per-run sequence for batch-unique activity-label trace-seed fallbacks. */
+  private activityLabelSeq = 0;
   private _haltedReason: string | undefined;
 
   private constructor(config: Partial<t.RunConfig>) {
@@ -1478,6 +1489,291 @@ export class Run<_T extends t.BaseGraphState> {
       await disposeLangfuseHandler(titleLangfuseHandler);
     }
   }
+
+  /**
+   * Generates a short activity label for a completed tool/reasoning block
+   * using a fast model. Mirrors `generateTitle`'s Langfuse wiring so the
+   * call is traced under the conversation's session (sessionId from
+   * `chainOptions.configurable.thread_id`) with its own tags — never as an
+   * orphan trace. The payload contains no human messages by design: intent
+   * comes from `lastAssistantText`, content from reasoning excerpts and
+   * tool entries.
+   */
+  async generateActivityLabel({
+    provider,
+    clientOptions,
+    entries,
+    thinkingExcerpts,
+    lastAssistantText,
+    prompt,
+    charLimit = 600,
+    chainOptions,
+    traceSeed,
+    agentId,
+  }: t.RunActivityLabelOptions): Promise<{ label?: string }> {
+    if (
+      entries.length === 0 &&
+      !(thinkingExcerpts && thinkingExcerpts.length > 0)
+    ) {
+      return {};
+    }
+    const labelSeq = ++this.activityLabelSeq;
+
+    /** Resolve the LABELED agent's context: its Langfuse overlay carries the
+     *  trace metadata and the tool-output redaction policy that must govern
+     *  this label. */
+    const requestedContext =
+      this.Graph == null || agentId == null
+        ? undefined
+        : this.Graph.agentContexts.get(agentId);
+    /** Fail closed: an explicit but unknown/stale `agentId` must NOT silently
+     *  fall back to the default agent, whose redaction policy may be weaker
+     *  than the labeled agent's. Skip generation entirely instead. */
+    if (agentId != null && requestedContext == null) {
+      return {};
+    }
+    const labelContext =
+      this.Graph == null
+        ? undefined
+        : (requestedContext ??
+          this.Graph.agentContexts.get(this.Graph.defaultAgentId));
+    const traceMetadata = createLangfuseTraceMetadata({
+      messageId: 'activity-label-' + this.id,
+      agentName: labelContext?.name,
+    });
+    const labelRunName = getLangfuseTraceName(
+      traceMetadata,
+      'LibreChat Activity Label'
+    );
+
+    /** Shallow-cloned: activity labels run once per tool batch, and writing
+     *  the Langfuse handler back onto a host-reused `chainOptions` would
+     *  accumulate duplicate callbacks across batches. */
+    const labelChainOptions = {
+      ...(chainOptions ?? {}),
+    } as Partial<RunnableConfig> & {
+      configurable?: Record<string, unknown>;
+    };
+    const labelUserId =
+      typeof labelChainOptions.configurable?.user_id === 'string'
+        ? (labelChainOptions.configurable.user_id as string)
+        : undefined;
+    const labelSessionId =
+      typeof labelChainOptions.configurable?.thread_id === 'string'
+        ? (labelChainOptions.configurable.thread_id as string)
+        : undefined;
+    const labelLangfuseConfig = resolveLangfuseConfig(
+      this.langfuse,
+      labelContext?.langfuse
+    );
+    initializeLangfuseTracing(labelLangfuseConfig);
+    /** Seed policy, threading two constraints:
+     *  1. `runWithLangfuseRuntimeContext` SPREADS the surrounding context, so
+     *     an absent seed INHERITS the parent run's and collapses every label
+     *     into that trace. When a parent seed is active we must override it
+     *     with a per-label one.
+     *  2. Without deterministic tracing there is no parent seed, and forcing
+     *     one here would make label trace ids deterministic when neither
+     *     `processStream` nor `generateTitle` are — so leave it unset.
+     *  Seeded when determinism is opted into OR a parent seed is live;
+     *  otherwise unseeded, matching the other generation paths. */
+    const inheritedTraceSeed = getTraceIdSeed();
+    const labelTraceSeed =
+      labelLangfuseConfig?.deterministicTraceId === true ||
+      inheritedTraceSeed != null
+        ? (traceSeed ?? `activity-label-${this.id}-${labelSeq}`)
+        : undefined;
+    const labelRuntimeScope = resolveLangfuseRuntimeScope({
+      runLangfuse: this.langfuse,
+      langfuseOverlay: labelContext?.langfuse,
+      traceIdSeed: labelTraceSeed,
+    });
+    /** Handler only when a session id resolved from
+     *  `chainOptions.configurable.thread_id`: without it the label call has
+     *  no conversation identity, and tracing it would create an orphan
+     *  trace outside any session — worse than not tracing at all. */
+    /** Declared then conditionally assigned (title precedent): a ternary
+     *  around the object literal makes eslint's indent rule and prettier
+     *  disagree, and both gate CI. */
+    let labelLangfuseHandler: CallbackEntry | undefined;
+    if (labelSessionId != null) {
+      labelLangfuseHandler = createLangfuseHandler({
+        langfuse: labelLangfuseConfig,
+        userId: labelUserId,
+        sessionId: labelSessionId,
+        traceMetadata,
+        tags: ['librechat', 'activity-label'],
+        traceIdSeed:
+          labelLangfuseConfig?.deterministicTraceId === true
+            ? labelTraceSeed
+            : undefined,
+      });
+    }
+    if (labelLangfuseHandler != null) {
+      labelChainOptions.callbacks = appendCallbacks(
+        labelChainOptions.callbacks,
+        [labelLangfuseHandler]
+      );
+    }
+
+    /** The label prompt becomes Langfuse generation input, so the resolved
+     *  tool-output redaction policy (global disable / redactedToolNames)
+     *  applies to it exactly as to structured tool observations. */
+    let redaction = hasToolOutputTracingConfig(
+      this.langfuse,
+      labelContext?.langfuse
+    )
+      ? resolveToolOutputTracingConfig(this.langfuse, labelContext?.langfuse)
+      : undefined;
+    /** Multi-agent graph with no `agentId`: the caller did not say WHICH
+     *  agent ran this batch, so resolving from the default agent could trace
+     *  raw output that a stricter sibling's policy forbids. Fold every
+     *  agent's policy into the strictest one instead of guessing. */
+    const agentContexts = this.Graph?.agentContexts;
+    if (agentId == null && agentContexts != null && agentContexts.size > 1) {
+      for (const context of agentContexts.values()) {
+        if (!hasToolOutputTracingConfig(this.langfuse, context.langfuse)) {
+          continue;
+        }
+        const candidate = resolveToolOutputTracingConfig(
+          this.langfuse,
+          context.langfuse
+        );
+        if (redaction == null) {
+          redaction = candidate;
+          continue;
+        }
+        redaction = {
+          enabled: redaction.enabled === false ? false : candidate.enabled,
+          redactedToolNames: new Set([
+            ...redaction.redactedToolNames,
+            ...candidate.redactedToolNames,
+          ]),
+          redactedToolNameMatchMode:
+            redaction.redactedToolNameMatchMode === 'partial' ||
+            candidate.redactedToolNameMatchMode === 'partial'
+              ? 'partial'
+              : 'exact',
+          redactionText: redaction.redactionText,
+        };
+      }
+    }
+    /** An active redaction policy suppresses free-form reasoning/intent, so
+     *  a reasoning-only block has nothing describable left — skip the model
+     *  call rather than paying for a label built from the prompt alone. */
+    const freeFormSuppressed =
+      redaction != null &&
+      (redaction.enabled === false || redaction.redactedToolNames.size > 0);
+    if (entries.length === 0 && freeFormSuppressed) {
+      return {};
+    }
+    const userPrompt = buildActivityLabelPrompt({
+      entries,
+      charLimit,
+      thinkingExcerpts,
+      lastAssistantText,
+      redaction,
+    });
+
+    const model = initializeModel({
+      provider,
+      clientOptions: {
+        ...(clientOptions ?? {}),
+        streaming: false,
+      } as t.ClientOptions,
+    }) as t.ChatModelInstance;
+
+    /** Distinct run id per label call: callback/tracing integrations key
+     *  in-flight runs by it, so reusing the parent run's id would collide
+     *  across successive (or concurrent) label batches. */
+    const labelRunId = `${this.id}-activity-${labelSeq}`;
+    const invokeConfig = Object.assign({}, labelChainOptions, {
+      run_id: labelRunId,
+      runId: labelRunId,
+      runName: labelChainOptions.runName ?? labelRunName,
+    }) as Partial<RunnableConfig>;
+
+    const invokeLabel = (
+      runtimeConfig: Partial<RunnableConfig>
+    ): Promise<unknown> =>
+      withLangfuseAttributes(
+        {
+          langfuse: labelLangfuseConfig,
+          userId: labelUserId,
+          sessionId: labelSessionId,
+          traceName: runtimeConfig.runName ?? labelRunName,
+          traceMetadata,
+          tags: ['librechat', 'activity-label'],
+        },
+        () =>
+          model.invoke(
+            [
+              new SystemMessage(prompt ?? ACTIVITY_LABEL_PROMPT),
+              new HumanMessage(userPrompt),
+            ],
+            runtimeConfig
+          )
+      );
+
+    const extractLabel = (response: unknown): string => {
+      const content = (response as { content?: unknown } | null)?.content;
+      let text = '';
+      if (typeof content === 'string') {
+        text = content;
+      } else if (Array.isArray(content)) {
+        text = content
+          .map((block) =>
+            typeof block === 'string'
+              ? block
+              : ((block as { text?: string }).text ?? '')
+          )
+          .join('');
+      }
+      return text.trim().replace(/^["']|["']$/g, '');
+    };
+
+    try {
+      let response: unknown;
+      try {
+        response = await withLangfuseRuntimeScope(labelRuntimeScope, () =>
+          invokeLabel(invokeConfig)
+        );
+      } catch (error) {
+        /** Retry ONLY recognized callback/tracer failures (the EventStream
+         *  tracer class of errors the stripped-callbacks fallback exists
+         *  for). Aborts and provider failures rethrow — retrying those
+         *  doubles traffic/cost and can restart cancelled requests. */
+        const aborted =
+          (labelChainOptions as { signal?: AbortSignal }).signal?.aborted ===
+            true || (error as Error | null)?.name === 'AbortError';
+        const callbackFailure = /callback|tracer|event.?stream/i.test(
+          String(
+            (error as Error | null)?.stack ??
+              (error as Error | null)?.message ??
+              ''
+          )
+        );
+        if (aborted || !callbackFailure) {
+          throw error;
+        }
+        const langfuseHandler = findCallback(
+          invokeConfig.callbacks,
+          isLangfuseCallbackHandler
+        );
+        const { callbacks: _cb, ...rest } = invokeConfig;
+        const safeConfig = Object.assign({}, rest, {
+          callbacks: langfuseHandler ? [langfuseHandler] : [],
+        });
+        response = await withLangfuseRuntimeScope(labelRuntimeScope, () =>
+          invokeLabel(safeConfig as Partial<RunnableConfig>)
+        );
+      }
+      const label = extractLabel(response);
+      return label.length > 0 ? { label } : {};
+    } finally {
+      await disposeLangfuseHandler(labelLangfuseHandler);
+    }
+  }
 }
 
 function findLastMessageOfType(

package/src/specs/activity-label-prompt.test.ts

@@ -0,0 +1,128 @@
+import type { ActivityLabelToolEntry } from '@/types/activityLabel';
+import { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT } from '@/langfuseToolOutputTracing';
+import { buildActivityLabelPrompt } from '@/prompts/activityLabel';
+import { resolveToolOutputTracingConfig } from '@/langfuseConfig';
+
+const entries: ActivityLabelToolEntry[] = [
+  {
+    toolName: 'web_search',
+    toolInput: { query: 'runtime versions' },
+    toolOutput: 'PUBLIC_SEARCH_RESULTS',
+    status: 'success',
+  },
+  {
+    toolName: 'db_query',
+    toolInput: { sql: 'select 1' },
+    error: 'SECRET_CONNECTION_STRING_LEAK',
+    status: 'error',
+  },
+];
+
+describe('buildActivityLabelPrompt redaction', () => {
+  it('embeds raw outputs and errors when no redaction policy resolves', () => {
+    const prompt = buildActivityLabelPrompt({ entries, charLimit: 600 });
+    expect(prompt).toContain('PUBLIC_SEARCH_RESULTS');
+    expect(prompt).toContain('SECRET_CONNECTION_STRING_LEAK');
+  });
+
+  it('redacts every outcome when tool-output tracing is globally disabled', () => {
+    const redaction = resolveToolOutputTracingConfig({
+      toolOutputTracing: { enabled: false },
+    });
+    const prompt = buildActivityLabelPrompt({
+      entries,
+      charLimit: 600,
+      redaction,
+    });
+    expect(prompt).not.toContain('PUBLIC_SEARCH_RESULTS');
+    expect(prompt).not.toContain('SECRET_CONNECTION_STRING_LEAK');
+    expect(prompt).toContain(LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT);
+    /** Tool names and inputs stay — matching the span processor, which
+     *  redacts output fields only. */
+    expect(prompt).toContain('web_search');
+    expect(prompt).toContain('runtime versions');
+  });
+
+  it('drops reasoning excerpts when any batch entry is redacted', () => {
+    const redaction = resolveToolOutputTracingConfig({
+      toolOutputTracing: { redactedToolNames: ['db_query'] },
+    });
+    const prompt = buildActivityLabelPrompt({
+      entries,
+      charLimit: 600,
+      thinkingExcerpts: [
+        'The db_query returned SECRET_CONNECTION_STRING_LEAK earlier',
+      ],
+      redaction,
+    });
+    expect(prompt).not.toContain('Reasoning excerpts');
+    expect(prompt).not.toContain('SECRET_CONNECTION_STRING_LEAK');
+  });
+
+  it('drops free-form context under ANY active policy, even with no matching entry', () => {
+    /** Reasoning/intent can quote output from an EARLIER call to the
+     *  redacted tool that this batch does not contain, so an active policy
+     *  suppresses free-form prose regardless of this batch's entries. */
+    const redaction = resolveToolOutputTracingConfig({
+      toolOutputTracing: { redactedToolNames: ['unrelated_tool'] },
+    });
+    const prompt = buildActivityLabelPrompt({
+      entries,
+      charLimit: 600,
+      thinkingExcerpts: ['Comparing versions across sources'],
+      lastAssistantText: 'Checking the unrelated_tool result from before',
+      redaction,
+    });
+    expect(prompt).not.toContain('Comparing versions across sources');
+    expect(prompt).not.toContain('Intent');
+    /** Non-matching entries keep their own outcomes. */
+    expect(prompt).toContain('PUBLIC_SEARCH_RESULTS');
+  });
+
+  it('keeps free-form context when no redaction policy is configured', () => {
+    const prompt = buildActivityLabelPrompt({
+      entries,
+      charLimit: 600,
+      thinkingExcerpts: ['Comparing versions across sources'],
+      lastAssistantText: 'Verifying each runtime',
+      redaction: undefined,
+    });
+    expect(prompt).toContain('Comparing versions across sources');
+    expect(prompt).toContain('Verifying each runtime');
+  });
+
+  it('bounds serialization of oversized structured tool output', () => {
+    const huge = Array.from({ length: 50_000 }, (_, i) => ({
+      id: i,
+      blob: 'x'.repeat(200),
+    }));
+    const prompt = buildActivityLabelPrompt({
+      entries: [
+        {
+          toolName: 'db_rows',
+          toolInput: { sql: 'select *' },
+          toolOutput: huge,
+          status: 'success',
+        },
+      ],
+      charLimit: 600,
+    });
+    /** Degrades to a shape summary instead of materializing ~10MB of JSON. */
+    expect(prompt).toContain('[Array(50000)]');
+    expect(prompt.length).toBeLessThan(2000);
+  });
+
+  it('redacts only named tools, including their error text', () => {
+    const redaction = resolveToolOutputTracingConfig({
+      toolOutputTracing: { redactedToolNames: ['db_query'] },
+    });
+    const prompt = buildActivityLabelPrompt({
+      entries,
+      charLimit: 600,
+      redaction,
+    });
+    expect(prompt).toContain('PUBLIC_SEARCH_RESULTS');
+    expect(prompt).not.toContain('SECRET_CONNECTION_STRING_LEAK');
+    expect(prompt).toContain(LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT);
+  });
+});

package/src/specs/activity-label-trace-seed.test.ts

@@ -0,0 +1,47 @@
+import {
+  resolveLangfuseRuntimeScope,
+  withLangfuseRuntimeScope,
+} from '@/langfuseRuntimeScope';
+import { getTraceIdSeed } from '@/langfuseRuntimeContext';
+
+/**
+ * `generateActivityLabel` passes one label seed to both the Langfuse handler
+ * and the runtime scope it invokes under. This proves the mechanism: a label
+ * scope's seed must override an inherited (parent run) seed for the duration
+ * of the label call, then restore — otherwise per-batch label generations
+ * collapse into the main run trace under deterministic tracing.
+ *
+ * Asserted through the ALS runtime-context channel (`getTraceIdSeed`), which
+ * the trace id generator consults alongside OTel context; tests run without
+ * a registered OTel context manager, so the OTel channel is a no-op here.
+ */
+describe('activity-label trace seed scoping', () => {
+  it('overrides an inherited run seed for the nested scope only', () => {
+    const runScope = resolveLangfuseRuntimeScope({ traceIdSeed: 'run-seed' });
+    withLangfuseRuntimeScope(runScope, () => {
+      expect(getTraceIdSeed()).toBe('run-seed');
+
+      const labelScope = resolveLangfuseRuntimeScope({
+        traceIdSeed: 'run-1-activity-3',
+      });
+      withLangfuseRuntimeScope(labelScope, () => {
+        expect(getTraceIdSeed()).toBe('run-1-activity-3');
+      });
+
+      expect(getTraceIdSeed()).toBe('run-seed');
+    });
+  });
+
+  it('keeps distinct seeds for successive label scopes', () => {
+    const seeds: Array<string | undefined> = [];
+    for (const seed of ['run-1-activity-0', 'run-1-activity-1']) {
+      withLangfuseRuntimeScope(
+        resolveLangfuseRuntimeScope({ traceIdSeed: seed }),
+        () => {
+          seeds.push(getTraceIdSeed());
+        }
+      );
+    }
+    expect(seeds).toEqual(['run-1-activity-0', 'run-1-activity-1']);
+  });
+});

package/src/specs/bedrock-toolless.live.test.ts

@@ -0,0 +1,123 @@
+// src/specs/bedrock-toolless.live.test.ts
+/**
+ * Live Bedrock verification for the tool-less-destination toolConfig fix.
+ *
+ * A tool-less agent in a multi-agent graph inherits the prior agent's
+ * toolUse/toolResult history. Because it binds no tools, Bedrock's Converse API
+ * rejects the request ("The toolConfig field must be defined when using toolUse
+ * and toolResult content blocks"). `foldToolBlocksForToollessAgent` folds that
+ * history into text so the request becomes valid.
+ *
+ * Run with:
+ * RUN_BEDROCK_LIVE_TESTS=1 BEDROCK_AWS_ACCESS_KEY_ID=... BEDROCK_AWS_SECRET_ACCESS_KEY=... \
+ *   BEDROCK_AWS_DEFAULT_REGION=us-west-2 npm test -- bedrock-toolless.live.test.ts --runInBand
+ */
+import { config as dotenvConfig } from 'dotenv';
+dotenvConfig();
+
+import {
+  AIMessage,
+  HumanMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import { beforeAll, describe, expect, it } from '@jest/globals';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+import { initializeModel } from '@/llm/init';
+import { foldToolBlocksForToollessAgent } from '@/messages';
+
+const accessKeyId =
+  process.env.BEDROCK_AWS_ACCESS_KEY_ID ?? process.env.AWS_ACCESS_KEY_ID;
+const secretAccessKey =
+  process.env.BEDROCK_AWS_SECRET_ACCESS_KEY ??
+  process.env.AWS_SECRET_ACCESS_KEY;
+
+const shouldRunLive =
+  process.env.RUN_BEDROCK_LIVE_TESTS === '1' &&
+  accessKeyId != null &&
+  accessKeyId !== '' &&
+  secretAccessKey != null &&
+  secretAccessKey !== '';
+
+const describeIfLive = shouldRunLive ? describe : describe.skip;
+
+const MODEL =
+  process.env.LIVE_BEDROCK_MODEL ??
+  'us.anthropic.claude-sonnet-4-5-20250929-v1:0';
+const REGION =
+  process.env.BEDROCK_AWS_DEFAULT_REGION ??
+  process.env.AWS_REGION ??
+  'us-west-2';
+
+/** History a tool-less destination inherits: a completed tool call, then a
+ *  follow-up user turn that itself invokes no tool. */
+function toollessHistory(): BaseMessage[] {
+  return [
+    new HumanMessage('Search my files for the roadmap.'),
+    new AIMessage({
+      content: '',
+      tool_calls: [
+        {
+          id: 'tt_live_1',
+          name: 'file_search',
+          args: { query: 'roadmap' },
+          type: 'tool_call',
+        },
+      ],
+    }),
+    new ToolMessage({
+      content: 'Found: roadmap.md — Q3 goals and milestones.',
+      tool_call_id: 'tt_live_1',
+      name: 'file_search',
+    }),
+    new AIMessage('I found roadmap.md with your Q3 goals.'),
+    new HumanMessage('thanks!'),
+  ];
+}
+
+describeIfLive('Bedrock tool-less destination (live)', () => {
+  let clientOptions: t.BedrockConverseClientOptions;
+
+  beforeAll(() => {
+    // Force SigV4 with the explicit keys; the Bedrock API-key (bearer) auth
+    // scheme otherwise takes precedence in the AWS SDK.
+    delete process.env.AWS_BEARER_TOKEN_BEDROCK;
+    // `shouldRunLive` already guarantees both keys are set; `?? ''` only keeps
+    // the credential fields typed as strings.
+    clientOptions = {
+      region: REGION,
+      model: MODEL,
+      credentials: {
+        accessKeyId: accessKeyId ?? '',
+        secretAccessKey: secretAccessKey ?? '',
+      },
+    };
+  });
+
+  it('rejects inherited tool history when the agent binds no tools', async () => {
+    const model = initializeModel({
+      provider: Providers.BEDROCK,
+      clientOptions,
+      tools: undefined,
+    });
+    await expect(model.invoke(toollessHistory())).rejects.toThrow(
+      /toolConfig field must be defined/i
+    );
+  }, 30000);
+
+  it('succeeds once inherited tool blocks are folded to text', async () => {
+    const model = initializeModel({
+      provider: Providers.BEDROCK,
+      clientOptions,
+      tools: undefined,
+    });
+    const folded = foldToolBlocksForToollessAgent(toollessHistory());
+    const res = await model.invoke(folded);
+    const text =
+      typeof res.content === 'string'
+        ? res.content
+        : JSON.stringify(res.content);
+    expect(text.length).toBeGreaterThan(0);
+  }, 30000);
+});

package/src/types/activityLabel.ts

@@ -0,0 +1,55 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ClientOptions } from '@/types/llm';
+import type { Providers } from '@/common';
+
+/** One tool call's contribution to the label payload (host-assembled). */
+export type ActivityLabelToolEntry = {
+  toolName: string;
+  toolInput: unknown;
+  toolOutput?: unknown;
+  error?: string;
+  status: 'success' | 'error';
+};
+
+/**
+ * Options for `Run.generateActivityLabel`. The payload deliberately contains
+ * NO human messages: intent context comes from the assistant's own last text
+ * (Claude Code's pattern) and the block's reasoning excerpts (claude.ai's
+ * pattern) — user text stays out of this low-scrutiny pathway entirely.
+ *
+ * This SDK defines NO activity-label graph event and never dispatches one.
+ * Label lifecycle streaming is entirely host-owned: a host claims its own
+ * content slots and emits on its own transport, with a payload shape only
+ * it defines. The SDK surface here is exactly this method plus the
+ * `activity_label` content type's formatter exclusions.
+ */
+export type RunActivityLabelOptions = {
+  provider: Providers;
+  clientOptions?: ClientOptions;
+  /**
+   * Agent that executed the labeled batch. Selects that agent's Langfuse
+   * overlay (trace metadata AND tool-output redaction policy) instead of
+   * the graph default — a stricter per-agent policy must not be bypassed
+   * by labeling work the default agent never performed.
+   */
+  agentId?: string;
+  entries: ActivityLabelToolEntry[];
+  /** Truncated reasoning excerpts from the block being labeled. */
+  thinkingExcerpts?: string[];
+  /** Assistant's last text before the block (~200 chars), as intent context. */
+  lastAssistantText?: string;
+  /** Override for the default label system prompt. */
+  prompt?: string;
+  /** Per-entry serialization cap for the prompt. Default 600. */
+  charLimit?: number;
+  /** LangChain runnable config carrier (signal, callbacks, thread/user ids). */
+  chainOptions?: Partial<RunnableConfig> & {
+    configurable?: Record<string, unknown>;
+  };
+  /**
+   * Seed for deterministic Langfuse trace ids (e.g. `${runId}-${slotIndex}`)
+   * so each batch's label gets a distinct, reproducible trace. When omitted,
+   * a per-run sequence keeps batches from collapsing into one trace.
+   */
+  traceSeed?: string;
+};