[wenjin272]

Linked issue: #1338 (Java implementation; Python follow-up after this PR merges).

Purpose of change

This PR changes Java implementation and tests only. Python will be aligned in a follow-up after the Java changes are merged. Unify individual await and mixed gather for ordinary, durable, Chat and subagent calls. ToolCallAction uses the same scheduler.

Runtime flow

Call execution

executeAsync         -> SingleAsyncFuture --------+
durableExecuteAsync  -> SingleDurableFuture ------+
chat                 -> SubgraphFuture -----------+--> call handles
subagent.submit      -> SubagentFutureImpl -------+
                       (delegates to a durable or subgraph Future)

call handles
  +-- individual await() ------------+
  +-- ctx.gather(handles).await() ---+--> shared scheduler
                                           |
                                           v
                                validate -> prepare -> start -> finish
                                close participants on every exit

ToolCallAction: parallel path

ToolCallAction
  |
  +-- ordinary Tool --> create durable handle for Tool.call --+
  |                                                           |
  +-- AsyncTool -----> callAsync returns a handle ------------+
                                                              |
                                                              v
                                             ctx.gather(handles).await()
                                                              |
                                                              v
                                          responses with original call IDs

Handle creation does not always start work: external async subagent submission happens before its result handle is returned. SubagentTool maps its handle to ToolResponse inside callAsync. Future inheritance, delegation and scheduler participation are detailed in the expandable section under Tests.

Key decisions

• Keep AsyncFuture as the public await interface. SchedulableFuture supplies runtime scheduling; GatherAsyncFuture only represents the batch result.
• Share SubgraphFuture between Chat and internal subagents. SubagentFutureImpl retains identity/query/cancellation/cleanup and delegates execution. MappedAsyncFuture converts results without another durable boundary.
• Keep Tool.call synchronous. Plan-layer AsyncTool accepts RunnerContext; runtime SubagentTool owns submission/normalization, supplied through ResourceContext.getSubagentTool.

Behavioral Semantics

Interaction decisions

Call / entry	Execution and recovery
Ordinary callable, single or gathered	Submit work through the runtime executor; cache locally without a durable slot.
Durable callable, single or gathered	Reserve a pending slot before execution; replay terminal results, reconcile pending calls when supported, otherwise rerun.
Chat / internal subagent	Use SubgraphFuture; graph waits do not occupy async workers. Requires a continuation or parallel engine.
Already-submitted external subagent	Submission stays separate; gathering waits for the existing remote call.
Tool call	Ordinary tools receive a framework durable wrapper; AsyncTool supplies its own handle. Parallel calls use gather.

Behavioral contracts

1. Results retain input order; completed handles reuse their cached outcomes on repeated awaits.
2. Individual await and gather share execution/recovery logic, but only gather applies batch parallelism and timeout settings.
3. Terminal records replay; pending calls recover. Ordinary calls are not persisted.
4. Duplicate calls, foreign-context handles, unsupported custom handles and nested batches are rejected.
5. Cancellation/failure releases subagent registrations. ContinuationNativeCallable executes on the calling thread.
6. Tool results retain call IDs, subagent normalization and metrics/reporting names.

Failure behavior

Ordinary callable exceptions become Outcome failures in gather and are rethrown by individual await. The scheduler propagates cancellation/interruption, UncapturableException and directly thrown Errors without recording terminal failures. An explicitly thrown CompletionException remains the original business exception, even when its cause is an Error. Timeout cancels unfinished work: started durable callables record timeout outcomes; unstarted callables and incomplete graphs retain pending records.

ToolCallAction converts non-cancellation Exceptions, including preparation/normalization failures, to tool responses. Invalid/cyclic subagent results become tool failures; cancellation and fatal Errors propagate. Exception classification in #1322 remains separate.

Tests

Contract	Evidence
1: ordering and cached awaits	MixedFutureGatherTest; JavaRunnerContextImplDurableExecuteAsyncTest
2: common lifecycle, single-call timeout isolation	schedulesInterfaceImplementationWithoutAsyncFutureBaseClass; singleAwaitDoesNotApplyBatchTimeout
3: replay, pending recovery and ordinary calls	partialRecoveryReplaysCompletedToolAndRestartsOnlyPendingGraph; completedRecoveryStartsNeitherWorkersNorGraphs; InternalSubagentRecoveryTest
4: input validation	duplicate/foreign/custom/nested-handle cases in JavaRunnerContextImplDurableExecuteAsyncTest
5: cleanup, cancellation and continuation-native execution	SubagentAwaitCleanupTest; cancellationNeverBecomesADurableOutcome; testDurableExecuteAsyncContinuationNativeReconcilableRunsInline
6: tool adaptation and reporting	ToolCallActionSubagentTest; ToolCallActionReportTest
Failure identity and fatal propagation	explicitCompletionExceptionPreservesBusinessFailure; packaged AsyncBatchErrorPropagationTest

JDK 11: API/plan/runtime full suite: 2,994 tests, 76 skipped, zero failures/errors; Spotless passed. JDK 17: targeted API/plan/runtime regression: 488 tests, 46 skipped, zero failures/errors. JDK 21: clean targeted runtime and packaged integration run: 82 tests, one skipped, zero failures/errors.

Not verified: full Python/Java API parity, the complete repository suite, all live provider services, or cross-version savepoint upgrades. Python alignment is intentionally deferred.

Future relationships, implementation invariants and verification details

Future inheritance

Solid arrows mean extends; dashed arrows mean implements. SchedulableFuture is the runtime scheduling contract; SingleDurableFuture inherits its implementation from SingleAsyncFuture.

classDiagram
    direction TB
    class AsyncFuture {
        <<interface>>
    }
    class DurableFuture {
        <<interface>>
    }
    class SchedulableFuture {
        <<interface>>
    }
    class AsyncFutureImpl {
        <<abstract>>
    }
    class SubagentFuture {
        <<abstract>>
    }
    AsyncFuture <|-- DurableFuture
    AsyncFuture <|-- SchedulableFuture
    AsyncFuture <|.. AsyncFutureImpl
    AsyncFuture <|.. SubagentFuture
    AsyncFutureImpl <|-- SingleAsyncFuture
    SingleAsyncFuture <|-- SingleDurableFuture
    DurableFuture <|.. SingleDurableFuture
    AsyncFutureImpl <|-- SubgraphFuture
    DurableFuture <|.. SubgraphFuture
    AsyncFutureImpl <|-- MappedAsyncFuture
    AsyncFutureImpl <|-- GatherAsyncFuture
    SubagentFuture <|-- SubagentFutureImpl
    SubagentFuture <|-- CompletedSubagentFuture
    SchedulableFuture <|.. SingleAsyncFuture
    SchedulableFuture <|.. SubgraphFuture
    SchedulableFuture <|.. MappedAsyncFuture
    SchedulableFuture <|.. SubagentFutureImpl
    SchedulableFuture <|.. CompletedSubagentFuture

Loading

AsyncFutureImpl supplies shared await/result caching. SubagentFutureImpl retains the subagent API and delegates execution; it does not inherit from AsyncFutureImpl. SubgraphFuture serves both Chat and internal subagents.

Future delegation and scheduling

Wrapper	Holds / delegates to	Responsibility
SubagentFutureImpl	SubgraphFuture for internal calls; SingleDurableFuture for deferred calls or awaiting external results	Retains session/call identity, remote query/cancellation and cleanup.
MappedAsyncFuture	One SchedulableFuture source	Maps the result; shares call identity and adds no durable boundary.
GatherAsyncFuture	A list of SchedulableFuture participants	Invokes the shared scheduler and returns ordered Outcomes.

SchedulableFuture extends AsyncFuture and defines the runtime lifecycle. Its implementations are SingleAsyncFuture (inherited by SingleDurableFuture), SubgraphFuture, MappedAsyncFuture, SubagentFutureImpl and CompletedSubagentFuture. CompletedSubagentFuture supplies an already-available result without starting work.

GatherAsyncFuture does not implement SchedulableFuture. It represents the batch result; the scheduler operates on its participants. Nested gather handles are therefore rejected.

Review order and verification

1. 2457d6ee7 — ordinary async/durable scheduling and recovery.
2. 179fb1495 — Chat/subagent Future convergence and mixed gather.
3. 3d0dd6896 — AsyncTool, runtime SubagentTool and ToolCallAction integration.

Each commit includes its related tests. Split validation: first commit on JDK 11 (617 tests, 44 skipped); second commit on JDK 21 including clean-packaged integration tests (409 tests, 17 skipped); third commit on JDK 17 (655 tests, 57 skipped). All selected tests passed. Timeout-test synchronization was additionally verified on JDK 17: all 53 durable async context tests passed, followed by three successful repetitions of the three timeout cases.

DurableCallSlot reserves journal positions during prepare in input order; finish writes to the reserved index. Mapping shares underlying call identity and does not allocate another slot. A call-ID mismatch truncates the recorded suffix before reserving the new call. The scheduler fences queued work before cancellation, preserves available completions at timeout, and closes participants on every exit.

The JDK 11/17 saturation tests distinguish action workers waiting in await from callable bodies executing in the async pool. With two async workers, all action workers can wait while only two callables run. Existing checkpoint, drain, lifecycle and restore assertions remain in place. DecisionModel recovery tests capture pending state on cancellation and inject faults after terminal outcomes are persisted.

Clean reactor rebuilds remove stale Java 21 classes and previously shaded distribution contents. Tests use the Byte Buddy agent and repository Python environment for Java/Python bridge tests. JDK 21 skips Spotless; formatting is checked on JDK 11.

API

SubagentFuture implements AsyncFuture; DurableFuture inherits await. ResourceContext implementations must provide getSubagentTool. SubagentTool and its name prefix move out of API.

Tool.call and RunnerContext entry-point signatures stay unchanged. ctx.chat still returns ChatResult and throws for failed ChatResponseEvent.

Single async durable calls now reserve pending state before execution, including calls without a reconciler. On JDK 11/17, ordinary single async calls use the same worker pool as gathered calls. Python follows Java merge.

Documentation

• doc-needed
• doc-not-needed
• doc-included

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Codex CLI 0.153.4 (GPT-6; exact model version unavailable)

[sangkyoonnam]

Local tests on ee2aeb8 failed at both spots below (details inline). I can share the tests if that helps. On JDK 21, I ran mvn -o -B -pl runtime -am test -Dtest='MixedFutureGatherTest#submit*+control*+completionBetween*' -Dsurefire.failIfNoSpecifiedTests=false three times. Each run executed 6 tests and the same 3 failed. Can a subagent submit fail before its slot is reserved on the real ToolCallAction path, as the first test models?

[sangkyoonnam]

On recovery, a finished tool's record can be dropped here when the id at this index differs from the first run.

I modeled ToolCallAction.executeParallel by hand in a local test (not part of this PR). On the first run the subagent submit fails before it reserves its slot, so the tool lands at index 0 as tool-call:call-2. On recovery the submit succeeds, index 0 is now session#call-1, saved.matches(id) is false, and clearCallResultsFromAndPersist(index) removes the tool's terminal record. The tool then runs again (toolCalls is 2, expected 1).

I ran submitFailingBeforeSlotReservationOnFirstRunKeepsCompletedToolOnRecovery and submitPersistenceFailureOnFirstRunKeepsCompletedToolOnRecovery. Both failed in 3 of 3 runs. The controls controlNoSubmitFailureKeepsCompletedToolOnRecovery and controlRecordedSubmitFailureKeepsCompletedToolOnRecovery passed in 3 of 3 runs.

The test doesn't go through the real ToolCallAction, so I haven't shown the first-run state is reachable there. Possible direction (inference): make a failed submit still consume its slot so the first run and recovery agree on indices, or look the record up by id instead of truncating the suffix.

[wenjin272]

Thanks for catching this. I confirmed the path through the real ToolCallAction and operator recovery: a user-provided deferred prepare() or overridden async submitRequest() can throw before the durable call is created.

Fixed in 56a20dd using your first direction. The framework now reserves the call's durable slot before invoking preparation, records ordinary preparation failures in that same slot, and skips preparation when replaying a terminal outcome. The same handling covers awaitResult() preparation. Framework faults and cancellation still propagate without becoming terminal failure records.

SubagentPreparationRecoveryTest covers sequential and parallel tool dispatch, with a crash after the following ordinary tool's result is persisted. Recovery replays the preparation failure and reuses the tool result without executing it again. It also covers pending-state persistence failures. The focused suites pass on JDK 17 and 21.

[sangkyoonnam]

A call that completes after the sweep but before this finish(timeout) is recorded as a timeout failure.

isDone() only says whether the outcome is settled, not whether completion finished. So timeout != null builds Outcome.failure(timeout) and, for a started durable call, writes it with slot.finish(result). cancel() can't undo it, because completion.cancel(true) has no effect on a finished completion. The description says the scheduler "preserves available completions at timeout"; this window is after the sweep. The finish(timeout) branch is the same as before 0cecf5f, and the test still failed on ee2aeb8.

I injected that window in a local test (not part of this PR): a hook's preventStart() waits for the tool to finish, then sleeps 100 ms. completionBetweenSweepAndTimeoutFinishIsNotRecordedAsTimeout failed in 3 of 3 runs (isFailure() was true, expected false). The control controlCompletionBeforeDeadlineIsRecordedAsSuccess passed in 3 of 3 runs.

The window is narrow and I injected it by hand. Possible direction (inference): when timeout != null but completion already finished normally, take the finish(null) path, and keep canceled completions as timeouts.

[wenjin272]

Thanks, confirmed and fixed in 8ebe3ad. After cancellation, the shared scheduler rechecks each completion signal. If it completed and was not cancelled, we use finish(null) to preserve the actual result or exception; cancelled or unfinished calls still take the timeout path.

Added deterministic race tests in MixedFutureGatherTest for successful completion, ordinary failure, fatal Error, and Chat/internal-subagent completion between the timeout sweep and cancellation. They pass on JDK 21, including the latest rerun.