Turn Status¶
A turn is one piece of work a harness does on a session: from a user's message to the model's last answer, with every tool call in between.
spring-ai-session-turn records in the session's log whether a turn runs, under which run id, and why the last one ended.
This solves three problems that a plain conversation log has:
- Two harnesses can run one session at the same time. Two instances, or two browser tabs, append their messages in between each other's. With a turn status, the second one is refused.
- A running turn cannot be stopped from elsewhere. A stop button on another instance has nothing to write to. With a turn status, it records an interrupt that the running harness reads.
- A turn that waits for a person is lost on a restart. A tool call that needs a confirmation pauses the turn, and the pause lives only in memory. With a turn status, the question is in the log, and any instance can resume the turn with the answer.
The module works with any Spring AI session store, because it uses only what every store has: events of its own type, a read by type, and a version-checked append.
Using it¶
Add the dependency, with its version from the BOM:
<dependency>
<groupId>org.springaicommunity</groupId>
<artifactId>spring-ai-session-turn</artifactId>
</dependency>
Create the turn service on a Spring AI SessionService, and run each turn between start and end:
TurnService turns = new TurnService(sessionService);
TurnStatus turn;
try {
turn = turns.start(sessionId, runId);
}
catch (TurnInProgressException ex) {
return busy(ex.getRunId()); // another turn runs: refuse, a 409 for example
}
catch (TurnParkedException ex) {
return ask(turns.pendingQuestion(sessionId)); // the session waits for an answer
}
try {
// run the turn: call the model, run tools, append messages
turns.end(sessionId, turn, StopReason.END_TURN);
}
catch (RuntimeException ex) {
turns.end(sessionId, turn, StopReason.ERROR);
throw ex;
}
busy and ask stand for what your application does.
A refused start writes nothing and owns no turn.
That is why it stays outside the second try: there is no turn to end.
From anywhere else, a UI or another instance:
turns.status(sessionId); // RUNNING under run-7, or IDLE with a stop reason
turns.interrupt(sessionId, "user pressed stop"); // ends the running turn
TurnService keeps no state. It reads and writes through the SessionService, so you can create one per call or keep one.
What the log holds¶
Every change is an event in the session's log.
| Event type | Written when | Payload |
|---|---|---|
TURN.STATUS |
A turn starts, ends, parks or resumes | status, runId, stopReason |
TURN.INTERRUPT |
Someone asks the running turn to stop | reason |
TURN.QUESTION |
A turn stops to wait for an answer | kind, value |
TURN.ANSWER |
The answer arrives and the turn goes on | questionEventId, value |
None of these events carries a message. The session's active view holds message events only, so these events never reach a prompt, and a compaction never covers them. They stay in the log as the record of the session's turns.
The status of a session is its newest TURN.STATUS event.
A session without one is IDLE.
There is no status column and no second store: the log is the only source.
Status and stop reasons¶
A session is RUNNING while a turn runs, and IDLE otherwise.
An idle session tells why its last turn ended:
| Stop reason | Meaning |
|---|---|
END_TURN |
The turn ran to its end. |
ERROR |
The turn failed. |
INTERRUPTED |
Someone called interrupt. A TURN.INTERRUPT event sits right before it. |
CANCELLED |
The client stopped listening, a cancelled stream for example. Nobody asked the session to stop, so there is no TURN.INTERRUPT event. |
REQUIRES_ACTION |
The turn is parked on a question and waits for an answer. |
What each method does in each state¶
For the methods of the turn service, a session is in one of three states:
- Idle. No turn runs and no question is open. The status is
IDLEwith any stop reason butREQUIRES_ACTION, or the session has no status yet. - Running. A turn runs. The status is
RUNNING. - Parked. A turn stopped on a question and waits for the answer. The status is
IDLEwithREQUIRES_ACTION. See a turn that waits for a person.
stateDiagram-v2
direction LR
[*] --> Idle
Idle --> Running : start
Running --> Idle : end, interrupt
Running --> Parked : park
Parked --> Running : resume
| Method | Idle | Running | Parked |
|---|---|---|---|
start |
Starts a turn. | Throws TurnInProgressException. |
Throws TurnParkedException. |
end |
Writes nothing. | Ends the turn, when it is the caller's. | Writes nothing. |
park |
Writes nothing. | Parks the turn, when it is the caller's. | Writes nothing. |
interrupt |
Records the request. | Records the request and ends the turn with INTERRUPTED. |
Records the request. The question stays open. |
resume |
Throws IllegalStateException. |
Throws TurnInProgressException. |
Records the answer and runs the turn again. |
status and pendingQuestion only read.
Two rules of the parked state are easy to miss:
startrefuses a parked session. A new turn would leave the question open. Resume the session instead.interruptdoes not close a question. A parked session has no turn to stop, so the session stays parked. To close the question, resume with an answer that says the person moved on.
The run id¶
Every turn runs under a run id. The run id names the harness run that owns the turn: a request, a job, an agent run. The session does not interpret it.
startandresumetake a run id. When you passnull, they generate a random UUID. The returned status carries the run id either way.endandparktake the turn, not the run id. The turn is the status thatstartorresumereturned. A run id may repeat, so only that status tells one turn from a later one under the same run id.interrupttakes no run id. It ends whatever turn runs, so a stop button does not need to know the owner.- A refused start names the owner.
TurnInProgressException.getRunId()returns the run id of the turn that runs. - An idle session keeps the run id of its last turn, next to the stop reason.
A resume does not have to use the run id of the turn that parked.
The turn often resumes on another instance, or hours later, under a run of its own.
Pass the old run id to keep one run id across the pause, or pass null for a new one.
TurnStatus parked = turns.park(sessionId, turn, question); // IDLE, run-1, REQUIRES_ACTION
turns.resume(sessionId, parked.runId(), answer); // RUNNING under run-1 again
turns.resume(sessionId, null, answer); // or RUNNING under a new run id
How a change is written¶
Every method that changes the status follows the same steps.
It reads the log's version, then the current status, and decides.
Then it appends its events with the version it read.
If another writer appended in between, the store refuses the append, and the method reads again and decides again.
After five refused attempts it gives up with an IllegalStateException.
This is what makes two concurrent starts safe: both read the same version, both try to append, and the store accepts exactly one.
The activity of start:
flowchart TD
A([start sessionId, runId]) --> B[Read the log's version]
B --> C[Read the newest TURN.STATUS event]
C --> D{Does a turn run?}
D -- yes --> E([Throw TurnInProgressException<br/>with the running run id])
D -- no --> F{Is the session parked?}
F -- yes --> G([Throw TurnParkedException])
F -- no --> H[Append TURN.STATUS RUNNING<br/>against the version read]
H --> I{Did the store accept it?}
I -- yes --> J([Return RUNNING under the run id])
I -- no --> K{Fifth attempt?}
K -- no --> B
K -- yes --> L([Throw IllegalStateException])
end, interrupt, park and resume follow the same loop with their own decision:
endwrites only while the caller's turn runs. Otherwise it writes nothing and returns the status as it stands. So a harness ends only its own turn: a lateendnever ends a later turn, and an interrupt that landed first stands.interruptwrites theTURN.INTERRUPTevent and, when a turn runs, theTURN.STATUSevent that ends it, in one append.parkandresumeare described below.
The types¶
classDiagram
direction LR
class TurnService {
+TurnService(SessionService)
+status(sessionId) TurnStatus
+start(sessionId, runId) TurnStatus
+end(sessionId, turn, StopReason) TurnStatus
+interrupt(sessionId, reason) TurnStatus
+park(sessionId, turn, Question) TurnStatus
+pendingQuestion(sessionId) SessionEvent
+resume(sessionId, runId, answer) TurnStatus
+resume(sessionId, runId, questionEventId, answer) TurnStatus
}
class TurnStatus {
<<record>>
+status SessionStatus
+runId String
+stopReason StopReason
+since Instant
+eventId String
+isRunning() boolean
+stillRuns(turn) boolean
+isParked() boolean
}
class SessionStatus {
<<enumeration>>
IDLE
RUNNING
}
class StopReason {
<<enumeration>>
END_TURN
ERROR
INTERRUPTED
CANCELLED
REQUIRES_ACTION
}
class Question {
<<record>>
+kind String
+payload Object
}
class Answer {
<<record>>
+questionEventId String
+value Object
}
class ToolConfirmationQuestion {
<<record>>
+replyEventId String
+toolCalls List
+toQuestion() Question
}
class SessionService {
<<interface>>
+getEventVersion(sessionId) long
+appendEvents(sessionId, events, version) boolean
+getEvents(sessionId, filter) List
}
TurnService --> SessionService : reads and writes through
TurnService ..> TurnStatus : returns
TurnService ..> Question : parks on
TurnStatus --> SessionStatus
TurnStatus --> StopReason
Answer ..> Question : answers
ToolConfirmationQuestion ..> Question : converts to
SessionService is Spring AI's interface. TurnEventTypes holds the four event types, and SessionStatusEvents and QuestionEvents build and read the events. The diagram leaves those helpers out.
A turn that waits for a person¶
A turn can stop to ask a person something and go on later with the answer, on any instance, after any delay. The built-in kind of question is a tool confirmation: a tool call that needs a person's decision. A harness can also park on a question of its own kind.
parkwrites aTURN.QUESTIONevent and aTURN.STATUSeventIDLEwithREQUIRES_ACTION, in one append. The session is then parked. It holds no turn while the person thinks.pendingQuestionreturns the open question: the newestTURN.QUESTIONevent when noTURN.ANSWERfollows it.resumewrites aTURN.ANSWERevent that points at the question, and aTURN.STATUSeventRUNNING, in one append. Only a parked session resumes, so the same answer sent twice resumes once.resumewith a question id refuses when that question already has an answer. Pass the id of the question you read withpendingQuestion. Two callers that read the same question then cannot both resume: the second one fails, even when the turn has parked again on a new question in between.
ToolConfirmationQuestion is the shape of a tool confirmation.
It holds the event id of the stored reply and the reply's tool calls, each marked whether it waits for a decision.
The answer is Spring AI's ToolCallDecisions.
A harness parks a turn and a UI resumes it:
sequenceDiagram
participant H as Harness
participant U as UI
participant T as TurnService
participant S as SessionService
H->>T: start(sessionId, "run-1")
T->>S: getEventVersion, newest TURN.STATUS
T->>S: appendEvents [TURN.STATUS RUNNING]
Note over H: the model asks for a tool<br/>that needs a confirmation
H->>T: park(sessionId, turn, question)
T->>S: appendEvents [TURN.QUESTION,<br/>TURN.STATUS IDLE REQUIRES_ACTION]
Note over H,S: the harness may stop here, even restart
U->>T: pendingQuestion(sessionId)
T->>S: newest TURN.QUESTION or TURN.ANSWER
T-->>U: the question
U->>T: resume(sessionId, "run-2", decisions)
T->>S: appendEvents [TURN.ANSWER,<br/>TURN.STATUS RUNNING]
Note over U,S: the harness runs the allowed tools<br/>and the turn goes on
What it does not do¶
- No guard on the log. An append never needs a running turn. A harness that does not call
startstill appends its messages, also while another turn runs. So the turn status protects a session only when every harness that writes to it runs its turns through the turn service. - No lease. A turn whose harness died stays
RUNNINGuntil someone callsinterrupt, which ends it. A later version can add a lease that lets the next start take over a turn that ran too long. - One answer per question. The answer decides every tool call of the question at once. An application that collects decisions one by one holds them until it has all.
- No stop by itself. An interrupt changes the status. The harness that runs the turn learns of it only when it reads the status, between two model calls for example. Check with
turns.status(sessionId).stillRuns(turn). TheChatClientbinding does this check for you. - No transaction around it. Run the turn service outside a surrounding transaction. Inside one with repeatable read isolation, the version read does not see what another writer committed, and every attempt fails.