Skip to content

Commit 07549bd

Browse files
authored
Merge pull request #122 from aictrl-dev/fix/121-unknown-finish-retry
fix(session): retry steps that end without a finish reason (#121)
2 parents b0b6cf4 + 4df1f56 commit 07549bd

15 files changed

Lines changed: 1038 additions & 82 deletions

‎EVENTS.md‎

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ When the parsed `aictrl run --format json` handler starts, the CLI emits newline
1313

1414
`invocationID` is present on every event from `run --format json`. `sessionID` is present only after a real session has been created; invocation events never fabricate one.
1515

16-
The schema is versioned via `invocation_start.schemaVersion` and `session_start.schemaVersion`. This document describes **schema version `"1"`**. Consumers should pin to this version and treat unknown fields as forward-compatible additions.
16+
The schema is versioned via `invocation_start.schemaVersion` and `session_start.schemaVersion`. This document describes **schema version `"1"`**. Consumers should pin to this version and treat unknown fields and event types as forward-compatible additions. The `retry` event is an additive event type, so `SCHEMA_VERSION` remains `"1"`.
1717

1818
The invocation envelope covers accepted `run --format json` executions from the first line of the parsed handler through validation, bootstrap, session creation, and execution. Argument-parser failures, other commands, and process-global uncaught exceptions or unhandled rejections are outside this contract.
1919

@@ -176,6 +176,28 @@ Emitted immediately before `session_complete` when the session terminates abnorm
176176

177177
## Message Events
178178

179+
### `retry`
180+
181+
Emitted when a primary-session model attempt fails with a retryable error and the CLI schedules another attempt. This includes a thought-only `unknown` finish with no tool call or non-empty text. It is not emitted after retries are exhausted or for an `unknown` finish that includes text or a tool call.
182+
183+
```json
184+
{
185+
"type": "retry",
186+
"timestamp": 1741500000000,
187+
"schemaVersion": "1",
188+
"invocationID": "7d142250-8bdc-43df-99af-efa252db62a7",
189+
"sessionID": "session_01abc...",
190+
"attempt": 1,
191+
"code": "no_finish_reason",
192+
"next": 1741500001000
193+
}
194+
```
195+
196+
- `attempt` (number, **required**) — retry number, starting at 1.
197+
- `code` (string, **required**) — safe retry reason: `no_finish_reason`, `rate_limited`, `overloaded`, `server_error`, `network`, or `unknown`. Provider error text is omitted from this event.
198+
- `retry.code` `rate_limited` maps to `session_error.reason` `rate_limit`; `no_finish_reason`, `overloaded`, `server_error`, and `network` are retry-only codes.
199+
- `next` (number, **required**) — scheduled next-attempt time in Unix milliseconds.
200+
179201
### `message_complete`
180202

181203
Emitted when a primary-session assistant message finishes (one per LLM turn). Child-session assistant messages are
@@ -234,17 +256,20 @@ For compatibility with sessions written before usage provenance was persisted, a
234256

235257
A provider can finish an HTTP stream normally while reporting a failed model turn. `error` and `content-filter` finishes persist a nonretryable `APIError` with `data.metadata.finishReason`; they emit `message_complete.status: "error"`, `session_error.reason: "provider"`, a populated `session_complete.error`, and `invocation_complete.status: "error"`. Headless execution exits 1 after flushing output. Partial text, completed tools, and reported usage remain available. No automatic recovery is attempted.
236258

237-
| Finish or termination | Behavior |
238-
| ----------------------------- | -------------------------------------------------------------------------------------------- |
239-
| `error` | Failed model turn; session/invocation failure and exit 1. |
240-
| `content-filter` | Failed model turn with a visible content-filter message; exit 1. |
241-
| `stop` | Completed turn, including empty output. |
242-
| `tool-calls` | Completed model turn; run tools and continue the session loop. |
243-
| `length` | Existing behavior: completed turn; preserve the reason so consumers can identify truncation. |
244-
| `unknown` | Existing behavior: continue the session loop. |
245-
| Other nonempty finish | Existing behavior: end the loop without inferring failure from an unfamiliar reason. |
246-
| Thrown provider error | Existing retry/error handling; unrecoverable failures emit the failure lifecycle. |
247-
| Cancellation / stream timeout | Existing cancellation and timeout lifecycle; not reclassified as a provider finish error. |
259+
An `unknown` finish is triaged by delivered output. Nonempty text becomes `stop`; a delivered tool call continues the loop. With neither, the attempt is retried, its output parts and usage are rolled back, and a `retry` event is emitted for each scheduled retry. Snapshot patch parts remain available for reverting file changes from failed attempts. Exhaustion produces a terminal error with `data.metadata.finishReason: "unknown"`. A pending tool input alone does not count as a delivered call. The agent step cap emits a terminal error; when it applies to an unfinished model turn, the provider's finish reason is preserved rather than rewritten as `stop`.
260+
261+
| Finish or termination | Behavior |
262+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
263+
| `error` | Failed model turn; session/invocation failure and exit 1. |
264+
| `content-filter` | Failed model turn with a visible content-filter message; exit 1. |
265+
| `stop` | Completed turn, including empty output. |
266+
| `tool-calls` | Completed model turn; run tools and continue the session loop. |
267+
| `length` | Existing behavior: completed turn; preserve the reason so consumers can identify truncation. |
268+
| `unknown` | Text becomes `stop`; a delivered tool call continues; no visible output retries, then fails on exhaustion. |
269+
| Agent step cap | Terminal error; preserve the unfinished model turn's provider finish, or emit a session-level error after a subtask or compaction. |
270+
| Other nonempty finish | Existing behavior: end the loop without inferring failure from an unfamiliar reason. |
271+
| Thrown provider error | Existing retry/error handling; unrecoverable failures emit the failure lifecycle. |
272+
| Cancellation / stream timeout | Existing cancellation and timeout lifecycle; not reclassified as a provider finish error. |
248273

249274
With pinned Google SDK 2.0.54, `IMAGE_SAFETY`, `RECITATION`, `SAFETY`, `BLOCKLIST`, `PROHIBITED_CONTENT`, and `SPII` map to `content-filter`; `MALFORMED_FUNCTION_CALL` maps to `error`. `OTHER` and `FINISH_REASON_UNSPECIFIED` map to `other`, while `LANGUAGE` maps to `unknown`. These last mappings retain the behavior above; they do not prove successful task completion. Consumers can distinguish `other` from `stop` using `message_complete.finish`.
250275

‎packages/cli/src/cli/cmd/run.ts‎

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -565,7 +565,29 @@ export const RunCommand = cmd({
565565
async function loop() {
566566
const toggles = new Map<string, boolean>()
567567

568-
for await (const event of events.stream) {
568+
eventsLoop: for await (const event of events.stream) {
569+
if (event.type === "session.status") {
570+
const status = event.properties.status
571+
switch (status.type) {
572+
case "retry":
573+
if (event.properties.sessionID === sessionID) {
574+
if (emit("retry", { attempt: status.attempt, code: status.reason, next: status.next })) continue
575+
}
576+
break
577+
case "idle":
578+
if (event.properties.sessionID === sessionID) break eventsLoop
579+
if (childSessions.has(event.properties.sessionID)) {
580+
emit("subagent_complete", {
581+
subagentSessionID: event.properties.sessionID,
582+
parentSessionID: sessionID,
583+
})
584+
}
585+
break
586+
case "busy":
587+
break
588+
}
589+
}
590+
569591
if (event.type === "message.updated" && event.properties.info.role === "assistant") {
570592
const info = event.properties.info
571593
if (args.format === "json") {
@@ -760,18 +782,6 @@ export const RunCommand = cmd({
760782
}
761783
}
762784

763-
if (event.type === "session.status" && event.properties.status.type === "idle") {
764-
if (event.properties.sessionID === sessionID) {
765-
break
766-
}
767-
if (childSessions.has(event.properties.sessionID)) {
768-
emit("subagent_complete", {
769-
subagentSessionID: event.properties.sessionID,
770-
parentSessionID: sessionID,
771-
})
772-
}
773-
}
774-
775785
if (event.type === "permission.asked") {
776786
const permission = event.properties
777787
const ownSession = permission.sessionID === sessionID

‎packages/cli/src/provider/transform.ts‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,17 @@ function mimeToModality(mime: string): Modality | undefined {
2020
export namespace ProviderTransform {
2121
export const OUTPUT_TOKEN_MAX = Flag.AICTRL_EXPERIMENTAL_OUTPUT_TOKEN_MAX || 32_000
2222

23+
export function isGeminiTarget(model: Provider.Model) {
24+
// Proxy model IDs can use mixed case even when registry IDs are lowercase.
25+
const id = model.api.id.toLowerCase()
26+
return (
27+
model.providerID === "google" ||
28+
sdkKey(model.api.npm) === "google" ||
29+
id.includes("gemini") ||
30+
id.startsWith("google/")
31+
)
32+
}
33+
2334
// Maps npm package to the key the AI SDK expects for providerOptions
2435
function sdkKey(npm: string): string | undefined {
2536
switch (npm) {
@@ -171,6 +182,18 @@ export namespace ProviderTransform {
171182
return msgs
172183
}
173184

185+
function dropTrailingNonToolAssistant(msgs: ModelMessage[]): ModelMessage[] {
186+
// Gemini rejects requests ending on a model turn, including proxy routes.
187+
// A trailing text answer must go as well.
188+
// Unlike MessageV2's history filter, this also removes text-bearing turns.
189+
const user = msgs.some((msg) => msg.role === "user")
190+
if (!user) return msgs
191+
const last = msgs.at(-1)
192+
if (last?.role !== "assistant") return msgs
193+
if (Array.isArray(last.content) && last.content.some((part) => part.type === "tool-call")) return msgs
194+
return dropTrailingNonToolAssistant(msgs.slice(0, -1))
195+
}
196+
174197
function applyCaching(msgs: ModelMessage[], model: Provider.Model): ModelMessage[] {
175198
const system = msgs.filter((msg) => msg.role === "system").slice(0, 2)
176199
const final = msgs.filter((msg) => msg.role !== "system").slice(-2)
@@ -252,6 +275,10 @@ export namespace ProviderTransform {
252275
export function message(msgs: ModelMessage[], model: Provider.Model, options: Record<string, unknown>) {
253276
msgs = unsupportedParts(msgs, model)
254277
msgs = normalizeMessages(msgs, model, options)
278+
const key = sdkKey(model.api.npm)
279+
if (isGeminiTarget(model)) {
280+
msgs = dropTrailingNonToolAssistant(msgs)
281+
}
255282
if (
256283
(model.providerID === "anthropic" ||
257284
model.api.id.includes("anthropic") ||
@@ -265,7 +292,6 @@ export namespace ProviderTransform {
265292
}
266293

267294
// Remap providerOptions keys from stored providerID to expected SDK key
268-
const key = sdkKey(model.api.npm)
269295
if (key && key !== model.providerID && model.api.npm !== "@ai-sdk/azure") {
270296
const remap = (opts: Record<string, any> | undefined) => {
271297
if (!opts) return opts

‎packages/cli/src/session/message-v2.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ import { type SystemError } from "bun"
1717
import type { Provider } from "@/provider/provider"
1818

1919
export namespace MessageV2 {
20+
export function hasVisibleOutput(parts: Part[]) {
21+
return parts.some((part) => (part.type === "text" && !!part.text.trim()) || part.type === "tool")
22+
}
2023
export const OutputLengthError = NamedError.create("MessageOutputLengthError", z.object({}))
2124
export const AbortedError = NamedError.create("MessageAbortedError", z.object({ message: z.string() }))
2225
export const StructuredOutputError = NamedError.create(
@@ -599,6 +602,9 @@ export namespace MessageV2 {
599602
) {
600603
continue
601604
}
605+
if (!hasVisibleOutput(msg.parts)) {
606+
continue
607+
}
602608
const assistantMessage: UIMessage = {
603609
id: msg.info.id,
604610
role: "assistant",

0 commit comments

Comments
 (0)