@librechat/agents 3.6.3 → 3.6.5

package/src/tools/subagent/index.ts

@@ -17,3 +17,5 @@ export type {
   SubagentExecutorOptions,
   ChildGraphFactory,
 } from './SubagentExecutor';
+export { InMemorySubagentTaskStore } from './InMemorySubagentTaskStore';
+export type { InMemorySubagentTaskStoreOptions } from './InMemorySubagentTaskStore';

package/src/types/graph.ts

@@ -40,6 +40,7 @@ import type {
   TokenBudgetBreakdown,
 } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
+import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
 
@@ -352,6 +353,12 @@ export type StandardGraphInput = {
    * they already flow through the registry's `CHAT_MODEL_END` handler.
    */
   subagentUsageSink?: SubagentUsageSink;
+  /**
+   * Optional host-owned process-local task namespace for detached subagents.
+   * Presence enables `run_in_background` on the subagent tool. Child graphs
+   * do not inherit it, keeping background nesting disabled for the MVP.
+   */
+  subagentTasks?: SubagentTaskConfig;
   /**
    * True when this graph IS a subagent child run (set by `SubagentExecutor`
    * when it constructs the child graph). Drives the hook-input `agentId`
@@ -363,10 +370,10 @@ export type StandardGraphInput = {
    */
   subagentScope?: boolean;
   /**
-   * Cooperative preemption, forwarded from `RunConfig.preemption`. Only ever
-   * set on the top-level graph: a steer targets the conversation, so subagent
-   * children must run to completion and `buildChildInputs` does not propagate
-   * this field.
+   * Cooperative preemption, forwarded from `RunConfig.preemption`. Ordinary
+   * child graphs do not inherit it. Detached subagent tasks may receive their
+   * own internal parent-control source so an interrupt can reuse the same
+   * provider-safe sealing path without targeting the top-level conversation.
    */
   preemption?: StreamPreemption;
   /**
@@ -780,6 +787,17 @@ export interface LangfuseConfig {
    * payloads. Defaults to the Langfuse SDK behavior.
    */
   mediaUploadEnabled?: boolean;
+  /**
+   * Extra HTTP headers sent on every Langfuse export request (OTLP trace
+   * export and media uploads), for self-hosted instances behind an
+   * authenticating proxy or gateway.
+   *
+   * Deployment-level only: one exporter is shared by every span routed to a
+   * destination, so these cannot carry per-request or per-user identity.
+   * Headers participate in destination identity — see
+   * `getLangfuseDestinationKey`.
+   */
+  additionalHeaders?: Record<string, string>;
   metadata?: Record<string, string | number | boolean | null | undefined>;
   /**
    * Internal OTLP span attributes to attach to Langfuse observations before

package/src/types/index.ts

@@ -6,6 +6,7 @@ export * from './messages';
 export * from './run';
 export * from './skill';
 export * from './stream';
+export * from './subagentTasks';
 export * from './tools';
 export * from './summarize';
 export * from './activityLabel';

package/src/types/run.ts

@@ -10,6 +10,7 @@ import type {
   ToolOutputReferencesConfig,
   EagerEventToolExecutionConfig,
 } from '@/types/tools';
+import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 import type * as s from '@/types/stream';
@@ -234,6 +235,11 @@ export type RunConfig = {
    * the registered `CHAT_MODEL_END` handler as usual.
    */
   subagentUsageSink?: g.SubagentUsageSink;
+  /**
+   * Trusted process-local task namespace for detached subagent execution.
+   * Omit to preserve foreground-only subagent behavior.
+   */
+  subagentTasks?: SubagentTaskConfig;
   /**
    * Pre-constructed hook registry for this run. Hooks fire at lifecycle
    * points in `processStream` (RunStart, UserPromptSubmit, Stop,

package/src/types/subagentTasks.ts

@@ -0,0 +1,162 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { SubagentUpdateEvent } from './graph';
+import type { InjectedMessage } from './tools';
+
+/** Terminal and in-flight states for a detached subagent task. */
+export type SubagentTaskStatus =
+  | 'running'
+  | 'completed'
+  | 'error'
+  | 'cancelled';
+
+/** Where a pending parent message may enter the child run. */
+export type SubagentTaskBoundary = 'preempt' | 'tool' | 'turn';
+
+/** Parent-to-child control operations accepted while a task is running. */
+export type SubagentTaskControlCommand =
+  | { action: 'steer' | 'queue' | 'interrupt'; message: string }
+  | { action: 'cancel' }
+  | { action: 'cancel_message'; controlId: string };
+
+/** Small, payload-free progress view safe to retain between parent turns. */
+export interface SubagentTaskProgress {
+  phase: SubagentUpdateEvent['phase'];
+  at: number;
+  eventCount: number;
+  label?: string;
+}
+/** Read-only task metadata. Results are exposed only through `claim`. */
+export interface SubagentTaskSnapshot {
+  /** Handle for this child-thread execution lease within its trusted scope. */
+  taskId: string;
+  /**
+   * Stable logical thread identity shared by fresh execution leases. Required
+   * from stores that advertise `supportsThreadContinuation`; optional for
+   * legacy/process-local stores that do not expose a durable conversation.
+   */
+  threadId?: string;
+  subagentType: string;
+  status: SubagentTaskStatus;
+  createdAt: number;
+  updatedAt: number;
+  resultAvailable: boolean;
+  resultClaimed: boolean;
+  pendingControls: number;
+  progress?: SubagentTaskProgress;
+  error?: string;
+}
+
+export type SubagentTaskClaim =
+  | { status: 'running'; task: SubagentTaskSnapshot }
+  | { status: 'completed'; task: SubagentTaskSnapshot; result: string }
+  | { status: 'error'; task: SubagentTaskSnapshot; error: string }
+  | { status: 'cancelled'; task: SubagentTaskSnapshot; error: string }
+  | { status: 'claimed'; task: SubagentTaskSnapshot }
+  | { status: 'not_found' };
+
+export type SubagentTaskControlResult =
+  | {
+      status: 'accepted';
+      task: SubagentTaskSnapshot;
+      controlId?: string;
+    }
+  | { status: 'cancelled'; task: SubagentTaskSnapshot }
+  | { status: 'not_running'; task: SubagentTaskSnapshot }
+  | { status: 'not_found' }
+  | { status: 'control_not_found'; task: SubagentTaskSnapshot }
+  | { status: 'invalid'; message: string };
+
+/**
+ * Child-side view supplied to one detached execution. It intentionally owns
+ * only cancellation, bounded message drains, and payload-free progress — no
+ * request/response object or host transport can leak into retained task state.
+ */
+export interface SubagentTaskRuntime {
+  readonly taskId: string;
+  readonly signal: AbortSignal;
+  shouldPreempt(): boolean;
+  drain(boundary: SubagentTaskBoundary): InjectedMessage[];
+  closeTurn(): { closed: boolean; messages: InjectedMessage[] };
+  reportProgress(event: SubagentUpdateEvent): void;
+}
+
+export interface SubagentTaskStartRequest {
+  scopeId: string;
+  idempotencyKey: string;
+  /** Host/SDK-owned parent run identity for durable lineage. */
+  parentRunId: string;
+  /** Executing parent agent, when the graph has a stable agent identity. */
+  parentAgentId?: string;
+  /** Provider tool-call identity that created this execution lease. */
+  parentToolCallId: string;
+  /**
+   * Untrusted child-thread selector supplied by the parent model. A
+   * continuation-capable store MUST validate ownership, scope, lineage, and
+   * `subagentType` before loading any saved messages.
+   */
+  threadId?: string;
+  /** Untrusted new user-turn text for host persistence and audit. */
+  input: string;
+  /** Stable hash of model-writable inputs used to reject conflicting replays. */
+  requestFingerprint?: string;
+  /** Execution shape selected from the host-provided subagent catalog. */
+  subagentKind: SubagentUpdateEvent['subagentKind'];
+  subagentType: string;
+  /**
+   * Starts one ephemeral execution lease. The canonical child transcript is
+   * returned so a host-owned store may persist it for a later fresh run;
+   * retaining a graph/checkpoint after terminal completion is unnecessary.
+   */
+  run(
+    runtime: SubagentTaskRuntime,
+    initialMessages?: BaseMessage[]
+  ): Promise<{
+    content: string;
+    messages?: BaseMessage[];
+  }>;
+}
+
+export type SubagentTaskStartResult =
+  | {
+      accepted: true;
+      isNew: boolean;
+      task: SubagentTaskSnapshot;
+    }
+  | { accepted: false; reason: 'capacity' }
+  | { accepted: false; reason: 'thread_unavailable' }
+  | {
+      accepted: false;
+      reason: 'conflict';
+      task: SubagentTaskSnapshot;
+    };
+
+/**
+ * Host-replaceable store contract used by the SDK's subagent tool. The store
+ * should normally outlive individual `Run` instances. Durable hosts may
+ * persist the transcript returned by `run` under the task/thread
+ * lineage and start a fresh execution for a later turn.
+ */
+export interface SubagentTaskStore {
+  /**
+   * True only when `start` authorizes an existing `threadId`, loads its
+   * saved transcript, and supplies that transcript to `run`. The flag exposes
+   * the model-facing continuation field, so a store must fail closed for an
+   * unknown or unauthorized id rather than starting an empty child.
+   */
+  readonly supportsThreadContinuation?: boolean;
+  start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
+  get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
+  list(scopeId: string): SubagentTaskSnapshot[];
+  claim(scopeId: string, taskId: string): SubagentTaskClaim;
+  control(
+    scopeId: string,
+    taskId: string,
+    command: SubagentTaskControlCommand
+  ): SubagentTaskControlResult;
+}
+
+/** Trusted, host-selected task namespace. It is never model-writable. */
+export interface SubagentTaskConfig {
+  store: SubagentTaskStore;
+  scopeId: string;
+}