feat: Allow manually specifying parent run tree in traceable config (#126)

* Allow manually specifying parent run tree in traceable config

* Allow passing parent(null)

* Agents.md fixes

* Use singleton in both places

Author: jacoblee93

gradlew.bat

@@ -96,4 +96,8 @@ dependencies {
     testImplementation("org.mockito:mockito-core:5.14.2")
     testImplementation("org.mockito:mockito-junit-jupiter:5.14.2")
     testImplementation("org.mockito.kotlin:mockito-kotlin:4.1.0")
+
+    // LangChain4j for testing parallel tool execution context propagation
+    testImplementation("dev.langchain4j:langchain4j:1.12.2")
+    testImplementation("dev.langchain4j:langchain4j-core:1.12.2")
 }

langsmith-java-core/build.gradle.kts

@@ -193,6 +193,36 @@ internal val DEFAULT_PROJECT_NAME: String? by lazy {
 
 internal val DEFAULT_EXECUTOR: ExecutorService by lazy { Executors.newCachedThreadPool() }
 
+/**
+ * Controls how the parent [RunTree] is resolved for a traced run.
+ * - [AUTO] (default) — resolve the parent from the current thread's context.
+ * - [of]`(parent)` — use the given [RunTree] as the parent, regardless of thread context.
+ * - [none]`()` — force a new root trace, ignoring any active thread context.
+ *
+ * ```java
+ * TraceConfig.builder().parent(parent).build();   // child of parent
+ * TraceConfig.builder().parent(null).build();      // new root trace
+ * // .parent() not called                         // auto-resolve from thread
+ * ```
+ */
+class ParentConfig
+private constructor(internal val runTree: RunTree?, internal val isExplicit: Boolean) {
+    companion object {
+        /** Resolve the parent from the current thread's context (default). */
+        @JvmField val AUTO = ParentConfig(runTree = null, isExplicit = false)
+
+        /** Force a new root trace — no parent, even if one exists on the thread. */
+        @JvmField val NONE = ParentConfig(runTree = null, isExplicit = true)
+
+        /** Force a new root trace — no parent, even if one exists on the thread. */
+        @JvmStatic fun none(): ParentConfig = NONE
+
+        /** Use the given [RunTree] as the explicit parent. */
+        @JvmStatic
+        fun of(parent: RunTree): ParentConfig = ParentConfig(runTree = parent, isExplicit = true)
+    }
+}
+
 /**
  * Configuration for a traced run.
  *
@@ -254,6 +284,38 @@ class TraceConfig(
      * @see TraceProcessIO
      */
     val processTracedIO: TraceProcessIO<*, *>? = null,
+    /**
+     * Explicit parent [RunTree] override.
+     *
+     * By default the parent is resolved from the current thread's context. Set this to control
+     * parent linkage explicitly:
+     * - **[ParentConfig.of]`(parent)`** — attach this run as a child of `parent`, even on a thread
+     *   with no context (e.g. a framework-managed thread pool).
+     * - **[ParentConfig.none]`()`** — force this run to be a new root trace, even when a parent
+     *   exists on the current thread.
+     *
+     * ```java
+     * // Capture the parent on the originating thread
+     * RunTree parent = Tracing.getCurrentRunTree();
+     *
+     * // Force a child relationship on a worker thread
+     * TraceConfig child = TraceConfig.builder()
+     *     .name("my-tool")
+     *     .parent(parent)    // attach as child
+     *     .build();
+     *
+     * // Force a new root trace
+     * TraceConfig root = TraceConfig.builder()
+     *     .name("independent-trace")
+     *     .parent(null)      // new root, ignores thread-local
+     *     .build();
+     * ```
+     *
+     * @see ParentConfig
+     * @see getCurrentRunTree
+     * @see withParent
+     */
+    val parent: ParentConfig = ParentConfig.AUTO,
 ) {
     companion object {
         /** Creates a new [Builder] for constructing a [TraceConfig]. */
@@ -284,6 +346,7 @@ class TraceConfig(
         private var executor: ExecutorService? = null
         private var tracingEnabled: Boolean? = null
         private var processTracedIO: TraceProcessIO<*, *>? = null
+        private var parent: ParentConfig = ParentConfig.AUTO
 
         @JvmSynthetic
         internal fun from(config: TraceConfig) = apply {
@@ -296,6 +359,7 @@ class TraceConfig(
             executor = config.executor
             tracingEnabled = config.tracingEnabled
             processTracedIO = config.processTracedIO
+            parent = config.parent
         }
 
         /** The name of the run, displayed in LangSmith. */
@@ -332,6 +396,19 @@ class TraceConfig(
             this.processTracedIO = processTracedIO
         }
 
+        /**
+         * Sets the parent [RunTree] for this run.
+         *
+         * Pass a [RunTree] to attach this run as a child — useful for cross-thread context
+         * propagation. Pass `null` to force a new root trace, ignoring any parent that may be
+         * active on the current thread.
+         *
+         * @see TraceConfig.parent
+         */
+        fun parent(parent: RunTree?) = apply {
+            this.parent = if (parent != null) ParentConfig.of(parent) else ParentConfig.NONE
+        }
+
         /** Builds the [TraceConfig]. */
         fun build() =
             TraceConfig(
@@ -344,6 +421,7 @@ class TraceConfig(
                 executor = executor,
                 tracingEnabled = tracingEnabled,
                 processTracedIO = processTracedIO,
+                parent = parent,
             )
     }
 }
@@ -632,7 +710,11 @@ private fun toStringKeyedMap(value: Any?): Map<String, Any?>? {
 }
 
 private fun <T> executeTraced(config: TraceConfig, inputs: Map<String, Any?>?, block: () -> T): T {
-    val parentRun = CURRENT_RUN.get()
+    // Resolve parent: explicit config.parent always wins over thread-local.
+    //   AUTO (default)          → resolve from thread-local
+    //   ParentConfig.of(run)    → use that run as parent
+    //   ParentConfig.none()     → force new root trace (no parent)
+    val parentRun = if (config.parent.isExplicit) config.parent.runTree else CURRENT_RUN.get()
 
     // Merge config: child config wins, then parent, then defaults.
     val tracingEnabled = config.tracingEnabled ?: parentRun?.tracingEnabled ?: isTracingEnabled()