Skip to content

fix(agent): give task trace correlations a complete lifecycle (issue #228) - #380

Open
konlue wants to merge 1 commit into
agentic-ai-java:mainfrom
konlue:fix/issue228-task-trace-correlation-lifecycle
Open

konlue wants to merge 1 commit into
agentic-ai-java:mainfrom
konlue:fix/issue228-task-trace-correlation-lifecycle

Conversation

@konlue

@konlue konlue commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Describe what this PR does / why we need it

Issue #228 reports that TaskTraceCorrelation — the in-memory store linking the TaskTool delegation site to the TaskOutputTool receive site of background tasks — has no lifecycle at all: it has a forget method with zero production callers, entries are recorded before the repository submission so a rejection strands the record, and the map grows without bound. This PR gives the store a three-layer lifecycle and adds regression tests for the rejection, terminal-delivery and retention paths.

Root cause

TaskTool.apply records the correlation facts before calling taskRepository.putTask unguarded, so a rejected submission — the bounded repository throws RejectedExecutionException on full capacity, a duplicate task id or a closed repository — leaves a stranded record that nothing ever removes. On the happy path, TaskOutputTool returns terminal results without releasing the entry either, and the store itself has no retention, so with the default repository (which has no capacity or TTL at all) entries accumulate for the life of the process.

The fix

Three layers, all inside the tools/task package. First, TaskTool wraps putTask in a try/catch and rolls the record back with forget before rethrowing, which covers every rejection mode of the bounded repository plus executor submission failures; the record-then-submit ordering already guarantees the task cannot start before its correlation exists. Second, TaskOutputTool releases the entry once a terminal result (completed or failed) has been delivered — deliberately after the receive span was created and linked, so the polling window still establishes the link facts; non-terminal outcomes (still-running, timeout, interrupted) keep the entry so the next poll can link, matching the existing timeout contract test. Third, entries now carry an expiry stamp driven by an injectable clock with a configurable retention (30 minutes by default): correlation() removes and never serves an expired entry, and record() lazily sweeps stale ones, so a store with no consumers still converges without a janitor thread. The retention is independent of the repository type — the default, bounded and any injected repository all converge, and repository clear()/shutdown() simply leave no new records behind — so no new repository lifecycle listener API is needed, and the builder-owned store outlives a repository shutdown without being closed.

Testing

The new TaskTraceCorrelationLifecycleTest drives retention with a mutable clock: an expired entry is never served and is swept by the next record, a live entry is served until its window elapses, and forget stays idempotent and safe for unknown ids. Two tool-chain tests extend TaskToolTraceCorrelationTests: a capacity-full bounded repository rejects the background submission with RejectedExecutionException and leaves zero retained records (red before: one stranded record), and a terminal poll releases the correlation while a second poll still returns the full repository result (red before: the entry survived the delivery). The existing timeout-retains-correlation contract, the bounded repository rejection semantics and the whole task package pass unchanged (36/36 in the package, 1423 in the module with only the known Windows filesystem/ripgrep baseline failures), checkstyle and spring-javaformat clean.

Fixes #228

@konlue

konlue commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

Note on the failing build job: it fails in pnpm --dir argi-studio/agent-chat-ui audit --prod, which queries the vulnerability database live. This surfaced today — the same step passed on main on 2026-11-19 (run 44558278320) and fails identically on the unrelated #370 branch (run 44882915599), while every Java-side job (test, check-style, format, license, linter, secret) is green on this PR. It is the studio UI's dependency disclosure, not this change; the lockfile fix belongs to the argi-studio maintainers.

…gentic-ai-java#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.
@konlue
konlue force-pushed the fix/issue228-task-trace-correlation-lifecycle branch from 09c7700 to aeb62a5 Compare November 21, 2026 08:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] 为任务追踪关联记录补齐提交回滚与保留期清理

1 participant