Skip to content

Commit 4df1f56

Browse files
committed
fix(session): close round-4 review gaps in retry, step cap and docs (#121)
1 parent 054ee42 commit 4df1f56

8 files changed

Lines changed: 473 additions & 285 deletions

File tree

‎EVENTS.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@ Emitted when a primary-session model attempt fails with a retryable error and th
195195

196196
- `attempt` (number, **required**) — retry number, starting at 1.
197197
- `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.
198199
- `next` (number, **required**) — scheduled next-attempt time in Unix milliseconds.
199200

200201
### `message_complete`
@@ -255,17 +256,20 @@ For compatibility with sessions written before usage provenance was persisted, a
255256

256257
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.
257258

258-
| Finish or termination | Behavior |
259-
| ----------------------------- | -------------------------------------------------------------------------------------------- |
260-
| `error` | Failed model turn; session/invocation failure and exit 1. |
261-
| `content-filter` | Failed model turn with a visible content-filter message; exit 1. |
262-
| `stop` | Completed turn, including empty output. |
263-
| `tool-calls` | Completed model turn; run tools and continue the session loop. |
264-
| `length` | Existing behavior: completed turn; preserve the reason so consumers can identify truncation. |
265-
| `unknown` | Existing behavior: continue the session loop. |
266-
| Other nonempty finish | Existing behavior: end the loop without inferring failure from an unfamiliar reason. |
267-
| Thrown provider error | Existing retry/error handling; unrecoverable failures emit the failure lifecycle. |
268-
| 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. |
269273

270274
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`.
271275

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,14 @@ export namespace ProviderTransform {
2121
export const OUTPUT_TOKEN_MAX = Flag.AICTRL_EXPERIMENTAL_OUTPUT_TOKEN_MAX || 32_000
2222

2323
export function isGeminiTarget(model: Provider.Model) {
24+
// Proxy model IDs can use mixed case even when registry IDs are lowercase.
2425
const id = model.api.id.toLowerCase()
25-
return sdkKey(model.api.npm) === "google" || id.includes("gemini") || id.startsWith("google/")
26+
return (
27+
model.providerID === "google" ||
28+
sdkKey(model.api.npm) === "google" ||
29+
id.includes("gemini") ||
30+
id.startsWith("google/")
31+
)
2632
}
2733

2834
// Maps npm package to the key the AI SDK expects for providerOptions

‎packages/cli/src/session/processor.ts‎

Lines changed: 52 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,36 @@ export namespace SessionProcessor {
3535
let blocked = false
3636
let attempt = 0
3737
let needsCompaction = false
38+
const retried: MessageV2.ToolPart[] = []
39+
40+
async function patch() {
41+
if (!snapshot) return
42+
const result = await Snapshot.patch(snapshot)
43+
if (result.files.length) {
44+
await Session.updatePart({
45+
id: Identifier.ascending("part"),
46+
messageID: input.assistantMessage.id,
47+
sessionID: input.sessionID,
48+
type: "patch",
49+
hash: result.hash,
50+
files: result.files,
51+
})
52+
}
53+
snapshot = undefined
54+
}
55+
56+
function terminal(
57+
error: NonNullable<MessageV2.Assistant["error"]>,
58+
message?: string,
59+
): NonNullable<MessageV2.Assistant["error"]> {
60+
if (!MessageV2.APIError.isInstance(error)) return error
61+
return new MessageV2.APIError({
62+
message: message ?? error.data.message,
63+
statusCode: error.data.statusCode,
64+
isRetryable: error.data.isRetryable,
65+
metadata: error.data.metadata?.finishReason ? { finishReason: error.data.metadata.finishReason } : undefined,
66+
}).toObject()
67+
}
3868

3969
const result = {
4070
get message() {
@@ -50,6 +80,7 @@ export namespace SessionProcessor {
5080
while (true) {
5181
const parts = new Set<string>()
5282
const texts: MessageV2.TextPart[] = []
83+
const delivered = new Set<string>()
5384
const before = {
5485
finish: input.assistantMessage.finish,
5586
cost: input.assistantMessage.cost,
@@ -160,7 +191,10 @@ export namespace SessionProcessor {
160191
toolcalls[value.toolCallId] = part as MessageV2.ToolPart
161192
parts.add(part.id)
162193

163-
const history = await MessageV2.parts(input.assistantMessage.id)
194+
delivered.add(part.id)
195+
const history = [...retried, ...(await MessageV2.parts(input.assistantMessage.id))].filter(
196+
(part): part is MessageV2.ToolPart => part.type === "tool" && part.state.status !== "pending",
197+
)
164198
const lastThree = history.slice(-DOOM_LOOP_THRESHOLD)
165199

166200
if (
@@ -256,15 +290,14 @@ export namespace SessionProcessor {
256290
break
257291

258292
case "finish-step":
293+
const visible = { text: texts.some((part) => !!part.text.trim()), tool: delivered.size > 0 }
259294
const usage = Session.getUsage({
260295
model: input.model,
261296
usage: value.usage,
262297
metadata: value.providerMetadata,
263298
})
264299
input.assistantMessage.finish =
265-
value.finishReason === "unknown" && texts.some((part) => part.text.trim())
266-
? "stop"
267-
: value.finishReason
300+
value.finishReason === "unknown" && visible.text ? "stop" : value.finishReason
268301
input.assistantMessage.cost += usage.cost
269302
input.assistantMessage.tokens = usage.tokens
270303
input.assistantMessage.usageStatus = usage.usageStatus
@@ -299,12 +332,7 @@ export namespace SessionProcessor {
299332
cost: usage.cost,
300333
})
301334
await Session.updateMessage(input.assistantMessage)
302-
if (
303-
value.finishReason === "unknown" &&
304-
!MessageV2.hasVisibleOutput(
305-
(await MessageV2.parts(input.assistantMessage.id)).filter((part) => parts.has(part.id)),
306-
)
307-
) {
335+
if (value.finishReason === "unknown" && !visible.text && !visible.tool) {
308336
throw new MessageV2.APIError({
309337
message: "Provider ended stream without finishReason or a tool call.",
310338
isRetryable: true,
@@ -318,22 +346,7 @@ export namespace SessionProcessor {
318346
})
319347
break
320348
}
321-
if (snapshot) {
322-
const patch = await Snapshot.patch(snapshot)
323-
if (patch.files.length) {
324-
const id = Identifier.ascending("part")
325-
parts.add(id)
326-
await Session.updatePart({
327-
id,
328-
messageID: input.assistantMessage.id,
329-
sessionID: input.sessionID,
330-
type: "patch",
331-
hash: patch.hash,
332-
files: patch.files,
333-
})
334-
}
335-
snapshot = undefined
336-
}
349+
await patch()
337350
SessionSummary.summarize({
338351
sessionID: input.sessionID,
339352
messageID: input.assistantMessage.parentID,
@@ -424,22 +437,13 @@ export namespace SessionProcessor {
424437
}
425438
const retry = SessionRetry.retryable(error)
426439
if (retry !== undefined) {
427-
if (snapshot) {
428-
const patch = await Snapshot.patch(snapshot)
429-
if (patch.files.length) {
430-
const id = Identifier.ascending("part")
431-
parts.add(id)
432-
await Session.updatePart({
433-
id,
434-
messageID: input.assistantMessage.id,
435-
sessionID: input.sessionID,
436-
type: "patch",
437-
hash: patch.hash,
438-
files: patch.files,
439-
})
440-
}
441-
snapshot = undefined
442-
}
440+
// Keep the failed attempt's file changes available to revert tooling.
441+
await patch()
442+
retried.push(
443+
...(await MessageV2.parts(input.assistantMessage.id)).filter(
444+
(part): part is MessageV2.ToolPart => part.type === "tool" && delivered.has(part.id),
445+
),
446+
)
443447
for (const partID of parts) {
444448
await Session.removePart({
445449
sessionID: input.sessionID,
@@ -459,14 +463,10 @@ export namespace SessionProcessor {
459463
if (attempt > SessionRetry.MAX_RETRY_ATTEMPTS) {
460464
log.error("max retry attempts reached", { attempt, retry })
461465
input.assistantMessage.error = apiError
462-
? new MessageV2.APIError({
463-
message: `Max retry attempts (${SessionRetry.MAX_RETRY_ATTEMPTS}) reached: ${SessionRetry.reason(error)}`,
464-
statusCode: error.data.statusCode,
465-
isRetryable: error.data.isRetryable,
466-
metadata: error.data.metadata?.finishReason
467-
? { finishReason: error.data.metadata.finishReason }
468-
: undefined,
469-
}).toObject()
466+
? terminal(
467+
error,
468+
`Max retry attempts (${SessionRetry.MAX_RETRY_ATTEMPTS}) reached: ${SessionRetry.reason(error)}`,
469+
)
470470
: new NamedError.Unknown({
471471
message: `Max retry attempts (${SessionRetry.MAX_RETRY_ATTEMPTS}) reached: ${SessionRetry.reason(error)}`,
472472
}).toObject()
@@ -488,27 +488,14 @@ export namespace SessionProcessor {
488488
}
489489
}
490490
if (retry === undefined) {
491-
input.assistantMessage.error = error
491+
input.assistantMessage.error = terminal(error)
492492
await Bus.publish(Session.Event.Error, {
493493
sessionID: input.assistantMessage.sessionID,
494494
error: input.assistantMessage.error,
495495
})
496496
}
497497
}
498-
if (snapshot) {
499-
const patch = await Snapshot.patch(snapshot)
500-
if (patch.files.length) {
501-
await Session.updatePart({
502-
id: Identifier.ascending("part"),
503-
messageID: input.assistantMessage.id,
504-
sessionID: input.sessionID,
505-
type: "patch",
506-
hash: patch.hash,
507-
files: patch.files,
508-
})
509-
}
510-
snapshot = undefined
511-
}
498+
await patch()
512499
const p = await MessageV2.parts(input.assistantMessage.id)
513500
for (const part of p) {
514501
if (part.type === "tool" && part.state.status !== "completed" && part.state.status !== "error") {

‎packages/cli/src/session/prompt.ts‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -345,16 +345,23 @@ export namespace SessionPrompt {
345345
const agent = await Agent.get(lastUser.agent)
346346
const maxSteps = agent.steps ?? Infinity
347347
if (step > maxSteps) {
348-
if (lastAssistant) {
349-
lastAssistant.error = new MessageV2.APIError({
350-
message: `Agent step limit (${maxSteps}) reached before a final response.`,
351-
isRetryable: false,
352-
}).toObject()
353-
lastAssistant.finish = "stop"
348+
const error = new MessageV2.APIError({
349+
message: `Agent step limit (${maxSteps}) reached before a final response.`,
350+
isRetryable: false,
351+
}).toObject()
352+
if (
353+
lastAssistant &&
354+
(lastAssistant.finish === "tool-calls" || lastAssistant.finish === "unknown") &&
355+
!lastAssistant.summary &&
356+
!msgs
357+
.find((msg) => msg.info.id === lastAssistant.id)
358+
?.parts.some((part) => part.type === "tool" && part.tool === TaskTool.id)
359+
) {
360+
lastAssistant.error = error
354361
lastAssistant.time.completed = Date.now()
355362
await Session.updateMessage(lastAssistant)
356-
await Bus.publish(Session.Event.Error, { sessionID, error: lastAssistant.error })
357363
}
364+
await Bus.publish(Session.Event.Error, { sessionID, error })
358365
break
359366
}
360367
if (step === 1)

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,17 @@ describe("ProviderTransform.message - Gemini trailing assistant", () => {
3737
])
3838
})
3939

40+
test("Google provider ID identifies a custom registry model", () => {
41+
const target = model("@ai-sdk/openai-compatible", "custom-model")
42+
expect(ProviderTransform.isGeminiTarget(target)).toBe(true)
43+
expect(ProviderTransform.message([user, thought], target, {})).toEqual([user])
44+
})
45+
46+
test("mixed-case proxy IDs identify Gemini targets", () => {
47+
const target = { ...model("@ai-sdk/openai-compatible", "GoOgLe/Gemini-3"), providerID: "proxy" }
48+
expect(ProviderTransform.isGeminiTarget(target)).toBe(true)
49+
})
50+
4051
test.each([
4152
["@ai-sdk/gateway", "google/gemini-3-pro"],
4253
["@openrouter/ai-sdk-provider", "google/gemini-3-pro"],

0 commit comments

Comments
 (0)