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; + } + + } + +}