Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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()) {
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -31,33 +35,75 @@
* 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.
* <p>
* 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<String, AgentTraceContext> contextsByTaskId = new ConcurrentHashMap<>();
private final Map<String, StampedContext> 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() {
return new TaskTraceCorrelation();
}

/**
* 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<AgentTraceContext> 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());
}

/**
Expand All @@ -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) {

}

}
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -246,6 +251,60 @@ void failingSubAgentIsRecordedWithRedactedContent() {
assertThat(recorded).contains("<redacted>");
}

@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<Observation.Context> {

final List<Observation.Context> stopped = new CopyOnWriteArrayList<>();
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
}

}

}
Loading