fix(tools): a tool call does not hold a monitor while it waits for another thread (one and two processors) #115

Merged
james.maes merged 1 commits from fix/tool-call-admission-does-not-pin into develop 2026-11-17 21:43:15 +00:00
Owner

What

Tool calls no longer wait out their time limit on a server with one or two processors. This is the bottom of the stack: #112, #113 and #114 are stacked on it and carry it.

The defect (present on develop, proved by the independent review)

A tool call is a virtual thread. The first call of a turn works out what the person is offered, which asks the UI API on another virtual thread and waits for it (UiApiToolFamily.writableTables, ProcessToolFamily.runnableProcesses). ToolCallService.execute did that inside synchronized(admission), and the other calls of the batch waited to enter the same monitor. On JDK 21 a virtual thread that waits while it holds a monitor, or waits to enter one, keeps its carrier thread, and there are only as many carriers as processors. So:

  • with two processors, a batch of tool calls in one reply waited 60 seconds (toolCallTimeoutSeconds);
  • with one processor, every first tool call of a turn did;
  • after the timeout the person was offered no write and no process tool for that turn (the question fails closed).

The fix

An admission is guarded by a ReentrantLock instead of a monitor, in all five places that took it (execute, propose, withdraw, admission, writeRow). A virtual thread parked on a java.util.concurrent lock gives its carrier up, so the thread waited for runs. What the lock guards did not change.

The test, and how the build runs it

FewProcessorsTest (one tool call; a batch of six with a write and a process tool among them, each answered within 30 seconds and with the tool offered) runs three times in every build: with the machine's processors, and in JVMs with one and with two processors (-XX:ActiveProcessorCount, the new surefire executions one-processor and two-processors in qbit-assistant/pom.xml).

Without the fix (the same test, ToolCallService as on develop): the one-processor execution fails, 2 of 3 tests, after 127 seconds. With it: 3 of 3 in each execution, about 4 seconds each.

Build

Full gated build of this branch's head f4b279b (./mvnw verify: Checkstyle, SpotBugs, PMD, tests, coverage; no gate skipped): BUILD SUCCESS, 732 tests (603 in qbit-assistant, plus 3 and 3 in the two few-processor executions), 0 failures.

What a host must change

Nothing.

🤖 Generated with Claude Code

## What Tool calls no longer wait out their time limit on a server with one or two processors. This is the bottom of the stack: #112, #113 and #114 are stacked on it and carry it. ## The defect (present on `develop`, proved by the independent review) A tool call is a virtual thread. The first call of a turn works out what the person is offered, which asks the UI API on another virtual thread and waits for it (`UiApiToolFamily.writableTables`, `ProcessToolFamily.runnableProcesses`). `ToolCallService.execute` did that inside `synchronized(admission)`, and the other calls of the batch waited to enter the same monitor. On JDK 21 a virtual thread that waits while it holds a monitor, or waits to enter one, keeps its carrier thread, and there are only as many carriers as processors. So: - with two processors, a batch of tool calls in one reply waited 60 seconds (`toolCallTimeoutSeconds`); - with one processor, every first tool call of a turn did; - after the timeout the person was offered no write and no process tool for that turn (the question fails closed). ## The fix An admission is guarded by a `ReentrantLock` instead of a monitor, in all five places that took it (`execute`, `propose`, `withdraw`, `admission`, `writeRow`). A virtual thread parked on a `java.util.concurrent` lock gives its carrier up, so the thread waited for runs. What the lock guards did not change. ## The test, and how the build runs it `FewProcessorsTest` (one tool call; a batch of six with a write and a process tool among them, each answered within 30 seconds and with the tool offered) runs three times in every build: with the machine's processors, and in JVMs with one and with two processors (`-XX:ActiveProcessorCount`, the new surefire executions `one-processor` and `two-processors` in `qbit-assistant/pom.xml`). Without the fix (the same test, `ToolCallService` as on `develop`): the `one-processor` execution fails, 2 of 3 tests, after 127 seconds. With it: 3 of 3 in each execution, about 4 seconds each. ## Build Full gated build of this branch's head `f4b279b` (`./mvnw verify`: Checkstyle, SpotBugs, PMD, tests, coverage; no gate skipped): BUILD SUCCESS, 732 tests (603 in `qbit-assistant`, plus 3 and 3 in the two few-processor executions), 0 failures. ## What a host must change Nothing. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
james.maes added 1 commit 2026-11-17 19:37:32 +00:00
fix(tools): a tool call does not hold a monitor while it waits for another thread
maven / build (push) Successful in 9m40s
build / maven (push) Successful in 9m40s
f4b279b95d
A tool call is a virtual thread, and the first call of a turn works out what
the person is offered by waiting for another one. ToolCallService did that
inside synchronized(admission), which keeps the carrier thread: with two
processors a batch of tool calls, and with one processor every first tool
call of a turn, waited out toolCallTimeoutSeconds, and the person was then
offered no write and no process tool for that turn.

An admission is now guarded by a ReentrantLock. FewProcessorsTest runs in
JVMs with one and with two processors (two surefire executions) and fails
there without the fix.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
james.maes merged commit c3ffc97445 into develop 2026-11-17 21:43:15 +00:00
Sign in to join this conversation.