From aeb62a52498b142b5ae3f524a0363ccef4a83b5f Mon Sep 17 00:00:00 2001
From: konlue <2362586639@qq.com>
Date: Sat, 21 Nov 2026 16:19:42 +0800
Subject: [PATCH] fix(agent): give task trace correlations a complete lifecycle
(issue #228)
TaskTraceCorrelation recorded entries at the TaskTool delegation site
before taskRepository.putTask, so a rejected submission (bounded
repository capacity, duplicate id, closed repository) stranded the
record forever; and nothing in production ever called forget, so even
happy-path entries outlived their tasks and the map grew without bound.
The correlation now has a three-layer lifecycle: TaskTool rolls the
record back when putTask throws; TaskOutputTool releases the entry once
a terminal (completed or failed) result has been delivered - after the
receive span was linked, never before, so the polling window keeps
working and non-terminal outcomes (still-running, timeout, interrupted)
retain the entry for the next poll; and a retention window with an
injectable clock lazily sweeps whatever survives, independent of the
repository type, so default, bounded and injected repositories all
converge without new repository lifecycle APIs.
Tests: a capacity-rejected submission leaves zero retained records; a
terminal poll releases the correlation while the repository result stays
pollable; expired entries are never served and swept on the next record;
forget stays idempotent.
---
.../tools/task/TaskOutputTool.java | 14 +++
.../orchestration/tools/task/TaskTool.java | 11 +-
.../tools/task/TaskTraceCorrelation.java | 81 ++++++++++++-
.../task/TaskToolTraceCorrelationTests.java | 59 ++++++++++
.../TaskTraceCorrelationLifecycleTest.java | 107 ++++++++++++++++++
5 files changed, 266 insertions(+), 6 deletions(-)
create mode 100644 argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelationLifecycleTest.java
diff --git a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskOutputTool.java b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskOutputTool.java
index d6cb89f5b..3d3ea490f 100644
--- a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskOutputTool.java
+++ b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskOutputTool.java
@@ -137,6 +137,7 @@ else if (bgTask.getError() != null) {
result.append("\nCause: ").append(bgTask.getError().getCause().getMessage());
}
span.error(bgTask.getError()).outcome("failed");
+ releaseCorrelation(request.taskId());
return result.toString();
}
else if (!bgTask.isCompleted()) {
@@ -146,10 +147,23 @@ else if (!bgTask.isCompleted()) {
}
span.outcome(outcome != null ? outcome : "completed").success();
+ releaseCorrelation(request.taskId());
return result.toString();
}
}
+ /**
+ * Release the correlation once a terminal result has been delivered: the receive span
+ * was already linked above, so a later poll no longer needs the link facts. Non
+ * terminal outcomes (still-running, timeout, interrupted) keep the entry so a
+ * subsequent poll can still link.
+ */
+ private void releaseCorrelation(String taskId) {
+ if (this.traceCorrelation != null) {
+ this.traceCorrelation.forget(taskId);
+ }
+ }
+
/**
* Start the receive span as a consumer; when the delegation context is known (fan-in
* or long-running waits), the span links back to the delegation id instead of
diff --git a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTool.java b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTool.java
index 90b69b70b..2675d73f5 100644
--- a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTool.java
+++ b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTool.java
@@ -134,7 +134,16 @@ public String apply(Request request, ToolContext toolContext) {
if (this.traceCorrelation != null && taskContext != null) {
this.traceCorrelation.record(taskId, taskContext);
}
- this.taskRepository.putTask(taskId, () -> executeSubAgent(subAgent, prompt, parentConfig, taskContext));
+ try {
+ this.taskRepository.putTask(taskId, () -> executeSubAgent(subAgent, prompt, parentConfig, taskContext));
+ }
+ catch (RuntimeException e) {
+ // A rejected submission must not leave a stranded correlation record.
+ if (this.traceCorrelation != null) {
+ this.traceCorrelation.forget(taskId);
+ }
+ throw e;
+ }
return String.format(
"task_id: %s%n%nBackground task started. Use TaskOutput tool with task_id='%s' to retrieve results.",
taskId, taskId);
diff --git a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelation.java b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelation.java
index b17421c15..416f5d0e9 100644
--- a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelation.java
+++ b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelation.java
@@ -16,12 +16,16 @@
package io.github.agentic.ai.agent.orchestration.tools.task;
+import java.time.Clock;
+import java.time.Duration;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import io.github.agentic.ai.workflow.graph.observation.trace.AgentTraceContext;
+import org.springframework.util.Assert;
+
/**
* Shared, in-memory correlation store between the {@link TaskTool} delegation site and the
* {@link TaskOutputTool} receive site of background tasks.
@@ -31,10 +35,38 @@
* cannot be its child. Both sides instead reference the same {@link AgentTraceContext},
* whose delegation identifier becomes the span link key of the consumer. Entries are only
* recorded when an {@link AgentTracer} is enabled.
+ *
+ * Entries have a three-layer lifecycle (issue #228): a rejected submission rolls the record
+ * back at the delegation site, a terminal polled result releases it at the receive site once
+ * the receive span has been linked, and the retention window below sweeps whatever survives
+ * (tasks nobody polls for, repository clear or shutdown). The retention is deliberately long
+ * relative to a polling window and independent of the repository type, so the default, the
+ * bounded and any injected repository all converge without the store needing repository
+ * lifecycle hooks; a live entry is never dropped early just to reclaim space.
*/
public final class TaskTraceCorrelation {
- private final Map contextsByTaskId = new ConcurrentHashMap<>();
+ private final Map contextsByTaskId = new ConcurrentHashMap<>();
+
+ private final Clock clock;
+
+ private final Duration retention;
+
+ public TaskTraceCorrelation() {
+ this(Clock.systemUTC(), Duration.ofMinutes(30));
+ }
+
+ /**
+ * @param clock the time source driving retention
+ * @param retention how long a recorded correlation may live without being consumed
+ */
+ public TaskTraceCorrelation(Clock clock, Duration retention) {
+ Assert.notNull(clock, "clock must not be null");
+ Assert.notNull(retention, "retention must not be null");
+ Assert.isTrue(!retention.isNegative(), "retention must not be negative");
+ this.clock = clock;
+ this.retention = retention;
+ }
/** @return an empty correlation store */
public static TaskTraceCorrelation empty() {
@@ -42,22 +74,36 @@ public static TaskTraceCorrelation empty() {
}
/**
- * Record the correlation facts of a background delegation.
+ * Record the correlation facts of a background delegation. Expired entries are swept
+ * along the way so a store without consumers still converges to its live entries.
* @param taskId the background task id
* @param context the correlation facts captured at the delegation site
*/
public void record(String taskId, AgentTraceContext context) {
if (taskId != null && context != null) {
- this.contextsByTaskId.put(taskId, context);
+ sweepExpired();
+ this.contextsByTaskId.put(taskId, new StampedContext(context, deadline()));
}
}
/**
* @param taskId the background task id
- * @return the correlation facts recorded at the delegation site, if any
+ * @return the correlation facts recorded at the delegation site, if any; an expired
+ * entry is removed and never served
*/
public Optional correlation(String taskId) {
- return taskId == null ? Optional.empty() : Optional.ofNullable(this.contextsByTaskId.get(taskId));
+ if (taskId == null) {
+ return Optional.empty();
+ }
+ StampedContext stamped = this.contextsByTaskId.get(taskId);
+ if (stamped == null) {
+ return Optional.empty();
+ }
+ if (isExpired(stamped)) {
+ this.contextsByTaskId.remove(taskId, stamped);
+ return Optional.empty();
+ }
+ return Optional.of(stamped.context());
}
/**
@@ -70,4 +116,29 @@ public void forget(String taskId) {
}
}
+ /** Test observation point for the retention assertions. */
+ int retainedCount() {
+ return this.contextsByTaskId.size();
+ }
+
+ private void sweepExpired() {
+ this.contextsByTaskId.forEach((taskId, stamped) -> {
+ if (isExpired(stamped)) {
+ this.contextsByTaskId.remove(taskId, stamped);
+ }
+ });
+ }
+
+ private boolean isExpired(StampedContext stamped) {
+ return this.clock.instant().isAfter(stamped.expiresAt());
+ }
+
+ private java.time.Instant deadline() {
+ return this.clock.instant().plus(this.retention);
+ }
+
+ private record StampedContext(AgentTraceContext context, java.time.Instant expiresAt) {
+
+ }
+
}
diff --git a/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskToolTraceCorrelationTests.java b/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskToolTraceCorrelationTests.java
index 907fc9a78..d8dc364f3 100644
--- a/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskToolTraceCorrelationTests.java
+++ b/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskToolTraceCorrelationTests.java
@@ -15,11 +15,14 @@
*/
package io.github.agentic.ai.agent.orchestration.tools.task;
+import java.time.Duration;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.RejectedExecutionException;
import java.util.concurrent.atomic.AtomicReference;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@@ -55,6 +58,8 @@
import reactor.core.publisher.Flux;
import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.mock;
@DisplayName("TaskTool/TaskOutputTool cross-agent trace correlation tests")
class TaskToolTraceCorrelationTests {
@@ -246,6 +251,60 @@ void failingSubAgentIsRecordedWithRedactedContent() {
assertThat(recorded).contains("");
}
+ @Test
+ @DisplayName("a rejected submission rolls back the recorded correlation")
+ void aRejectedSubmissionRollsBackTheCorrelation() {
+ ConfigCaptureHook captureHook = new ConfigCaptureHook();
+ ReactAgent child = subAgent("child_agent", new FixedResponseChatModel("unused"), captureHook);
+ AgentTracer tracer = enabledTracer();
+ TaskTraceCorrelation correlation = TaskTraceCorrelation.empty();
+ ExecutorService stalled = mock(ExecutorService.class);
+ try (BoundedTaskRepository repository = new BoundedTaskRepository(stalled, 1, 0, 1, Duration.ofMinutes(1))) {
+ repository.putTask("occupy", () -> "occupy");
+ TaskTool tool = new TaskTool(Map.of("child_agent", child), repository, tracer, correlation);
+
+ assertThatThrownBy(() -> tool.apply(new TaskTool.Request("desc", "prompt", "child_agent", true),
+ toolContext(parentConfig()))).isInstanceOf(RejectedExecutionException.class);
+
+ assertThat(correlation.retainedCount())
+ .as("the submission was rejected, so no correlation may remain")
+ .isZero();
+ assertThat(captureHook.capturedConfig())
+ .as("the rejected delegation must not have executed the sub-agent")
+ .isNull();
+ }
+ }
+
+ @Test
+ @DisplayName("a terminal result releases the correlation while the repository result stays pollable")
+ void aTerminalResultReleasesTheCorrelationForLaterPolls() throws Exception {
+ ConfigCaptureHook captureHook = new ConfigCaptureHook();
+ ReactAgent child = subAgent("child_agent", new FixedResponseChatModel("child response"), captureHook);
+ AgentTracer tracer = enabledTracer();
+ TaskTraceCorrelation correlation = TaskTraceCorrelation.empty();
+ DefaultTaskRepository repository = new DefaultTaskRepository();
+ TaskTool tool = new TaskTool(Map.of("child_agent", child), repository, tracer, correlation);
+ TaskOutputTool output = new TaskOutputTool(repository, tracer, correlation);
+
+ String launchResult = tool.apply(new TaskTool.Request("desc", "prompt", "child_agent", true),
+ toolContext(parentConfig()));
+ Matcher matcher = Pattern.compile("task_id: (task_[a-f0-9\\-]+)").matcher(launchResult);
+ assertThat(matcher.find()).isTrue();
+ String taskId = matcher.group(1);
+
+ String firstPoll = output.apply(new TaskOutputTool.Request(taskId, true, 10000L), toolContext(parentConfig()));
+
+ assertThat(firstPoll).contains("Status: Completed").contains("child response");
+ assertThat(correlation.retainedCount())
+ .as("the terminal result was delivered with its link, so the correlation is released")
+ .isZero();
+
+ String secondPoll = output.apply(new TaskOutputTool.Request(taskId, false, 1L), toolContext(parentConfig()));
+
+ assertThat(secondPoll).as("the repository result itself is untouched").contains("Status: Completed")
+ .contains("child response");
+ }
+
static final class RecordingHandler implements ObservationHandler {
final List stopped = new CopyOnWriteArrayList<>();
diff --git a/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelationLifecycleTest.java b/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelationLifecycleTest.java
new file mode 100644
index 000000000..df6bda975
--- /dev/null
+++ b/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/tools/task/TaskTraceCorrelationLifecycleTest.java
@@ -0,0 +1,107 @@
+/*
+ * Copyright 2025-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.agentic.ai.agent.orchestration.tools.task;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneOffset;
+
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTraceContext;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** 复现 #228:关联记录必须有保留期兜底,过期条目永不服务并被惰性清扫。 */
+class TaskTraceCorrelationLifecycleTest {
+
+ private final MutableClock clock = new MutableClock(Instant.parse("2026-11-21T12:00:00Z"));
+
+ private final TaskTraceCorrelation correlation = new TaskTraceCorrelation(clock, Duration.ofMinutes(30));
+
+ @Test
+ void anExpiredEntryIsNeverServedAndIsSweptByTheNextRecord() {
+ correlation.record("task-1", context("task-1"));
+
+ clock.advance(Duration.ofMinutes(31));
+
+ assertThat(correlation.correlation("task-1")).as("expired entries must never be served").isEmpty();
+ assertThat(correlation.retainedCount()).as("the expired entry must be gone").isZero();
+
+ correlation.record("task-2", context("task-2"));
+
+ assertThat(correlation.retainedCount()).as("the sweep must have removed the stale entry only").isEqualTo(1);
+ }
+
+ @Test
+ void aLiveEntryIsServedUntilItsRetentionElapses() {
+ correlation.record("task-1", context("task-1"));
+ assertThat(correlation.correlation("task-1")).isPresent();
+
+ clock.advance(Duration.ofMinutes(29));
+ assertThat(correlation.correlation("task-1")).as("inside the retention window").isPresent();
+
+ clock.advance(Duration.ofMinutes(2));
+ assertThat(correlation.correlation("task-1")).as("past the retention window").isEmpty();
+ }
+
+ @Test
+ void forgetIsIdempotentAndSafeForUnknownTaskIds() {
+ correlation.record("task-1", context("task-1"));
+
+ correlation.forget("task-1");
+ correlation.forget("task-1");
+ correlation.forget("unknown-task");
+
+ assertThat(correlation.retainedCount()).isZero();
+ assertThat(correlation.correlation("task-1")).isEmpty();
+ }
+
+ private AgentTraceContext context(String taskId) {
+ return AgentTraceContext.capture(null, null).withTaskId(taskId);
+ }
+
+ /** Mutable clock for deterministic retention tests (the #331 metrics pattern). */
+ private static final class MutableClock extends Clock {
+
+ private Instant now;
+
+ private MutableClock(Instant now) {
+ this.now = now;
+ }
+
+ private void advance(Duration duration) {
+ this.now = this.now.plus(duration);
+ }
+
+ @Override
+ public ZoneOffset getZone() {
+ return ZoneOffset.UTC;
+ }
+
+ @Override
+ public Clock withZone(java.time.ZoneId zone) {
+ return this;
+ }
+
+ @Override
+ public Instant instant() {
+ return this.now;
+ }
+
+ }
+
+}