Skip to content

Commit f4338f0

Browse files
vitalyiegorovclaude
andcommitted
fix(claude): name the expired login or usage limit instead of a generic API error
When Claude's OAuth session expires or a subscription usage window rejects the request, the CLI ends the turn with an opaque api_error and T3 showed "Claude gave up after repeated API errors." That reads as a provider outage. Latch the real cause per turn (the authentication_failed assistant event, or a rejected rate_limit_event) and report it when the turn ends as a generic api_error or a success flagged is_error. Every other terminal reason keeps its own message. No retry or provider status changes. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent 4f782be commit f4338f0

4 files changed

Lines changed: 218 additions & 3 deletions

File tree

‎apps/server/src/provider/Drivers/ClaudeHome.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import * as Effect from "effect/Effect";
66
import * as Path from "effect/Path";
77

88
import {
9+
claudeSignedOutMessage,
910
makeClaudeCapabilitiesCacheKey,
1011
makeClaudeContinuationGroupKey,
1112
makeClaudeEnvironment,
@@ -39,6 +40,13 @@ it.layer(NodeServices.layer)("ClaudeHome", (it) => {
3940
}),
4041
);
4142

43+
it("points the signed-out hint at the configured Claude home", () => {
44+
expect(claudeSignedOutMessage({ homePath: "" })).toContain("Run `claude auth login`");
45+
expect(claudeSignedOutMessage({ homePath: "~/.claude-work" })).toContain(
46+
"Run `CLAUDE_CONFIG_DIR=~/.claude-work claude auth login`",
47+
);
48+
});
49+
4250
it.effect("separates capability probes by cwd", () =>
4351
Effect.gen(function* () {
4452
const config = { binaryPath: "claude", homePath: "" };

‎apps/server/src/provider/Drivers/ClaudeHome.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,15 @@ export const makeClaudeCapabilitiesCacheKey = Effect.fn("makeClaudeCapabilitiesC
5050
return `${config.binaryPath}\0${resolvedHomePath}\0${cwd ?? ""}`;
5151
},
5252
);
53+
54+
/**
55+
* Login hint for a Claude CLI whose OAuth session expired. Names the
56+
* instance's config dir so multi-instance setups log back into the same one
57+
* the adapter spawns against.
58+
*/
59+
export const claudeSignedOutMessage = (config: Pick<ClaudeSettings, "homePath">): string => {
60+
const homePath = config.homePath.trim();
61+
return `Claude is signed out: its login session expired. Run \`${
62+
homePath ? `CLAUDE_CONFIG_DIR=${homePath} ` : ""
63+
}claude auth login\` in a terminal, then send the message again.`;
64+
};

‎apps/server/src/provider/Layers/ClaudeAdapter.test.ts‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2199,6 +2199,172 @@ describe("ClaudeAdapterLive", () => {
21992199
);
22002200
});
22012201

2202+
const AUTH_FAILURE_ASSISTANT = {
2203+
type: "assistant",
2204+
session_id: "sdk-session-auth",
2205+
uuid: "assistant-auth",
2206+
parent_tool_use_id: null,
2207+
error: "authentication_failed",
2208+
is_api_error_message: true,
2209+
message: {
2210+
id: "assistant-message-auth",
2211+
model: "<synthetic>",
2212+
content: [{ type: "text", text: "Not logged in \u00b7 Please run /login" }],
2213+
},
2214+
} as unknown as SDKMessage;
2215+
2216+
const completedTurn = (runtimeEvents: ReadonlyArray<ProviderRuntimeEvent>) => {
2217+
const event = runtimeEvents[runtimeEvents.length - 1];
2218+
assert.equal(event?.type, "turn.completed");
2219+
assert(event?.type === "turn.completed");
2220+
return event.payload;
2221+
};
2222+
2223+
it.effect.each([
2224+
{
2225+
name: "an api_error terminal reason",
2226+
result: { subtype: "success", is_error: false, terminal_reason: "api_error", errors: [] },
2227+
state: "failed",
2228+
errorMessage: /claude auth login/,
2229+
},
2230+
{
2231+
name: "an is_error success with no terminal reason",
2232+
result: { subtype: "success", is_error: true, errors: [] },
2233+
state: "failed",
2234+
errorMessage: /claude auth login/,
2235+
},
2236+
// Every other outcome names its own cause, and the latch must not speak over it.
2237+
{
2238+
name: "a terminal reason of its own",
2239+
result: {
2240+
subtype: "success",
2241+
is_error: false,
2242+
terminal_reason: "prompt_too_long",
2243+
errors: [],
2244+
},
2245+
state: "failed",
2246+
errorMessage: /prompt exceeds the model's context window/,
2247+
},
2248+
{
2249+
name: "a listed tool failure",
2250+
result: {
2251+
subtype: "error_during_execution",
2252+
is_error: true,
2253+
errors: ["Tool execution failed: EACCES"],
2254+
},
2255+
state: "failed",
2256+
errorMessage: /EACCES/,
2257+
},
2258+
{
2259+
name: "a user interrupt",
2260+
result: {
2261+
subtype: "error_during_execution",
2262+
is_error: true,
2263+
terminal_reason: "aborted_tools",
2264+
errors: [],
2265+
},
2266+
state: "interrupted",
2267+
errorMessage: undefined,
2268+
},
2269+
{
2270+
name: "a cancellation",
2271+
result: { subtype: "error_during_execution", is_error: true, errors: ["cancelled"] },
2272+
state: "cancelled",
2273+
errorMessage: /cancelled/,
2274+
},
2275+
])(
2276+
"reports the real cause when an expired login is followed by $name",
2277+
({ result, state, errorMessage }) => {
2278+
const harness = makeHarness();
2279+
return Effect.gen(function* () {
2280+
const adapter = yield* ClaudeAdapter;
2281+
2282+
const runtimeEventsFiber = yield* adapter.streamEvents.pipe(
2283+
Stream.takeUntil((event) => event.type === "turn.completed"),
2284+
Stream.runCollect,
2285+
Effect.forkChild,
2286+
);
2287+
2288+
const session = yield* adapter.startSession({
2289+
threadId: THREAD_ID,
2290+
provider: ProviderDriverKind.make("claudeAgent"),
2291+
runtimeMode: "full-access",
2292+
});
2293+
yield* adapter.sendTurn({ threadId: session.threadId, input: "hello", attachments: [] });
2294+
2295+
harness.query.emit(AUTH_FAILURE_ASSISTANT);
2296+
harness.query.emit({
2297+
type: "result",
2298+
...result,
2299+
session_id: "sdk-session-auth",
2300+
uuid: "result-auth",
2301+
} as unknown as SDKMessage);
2302+
2303+
const payload = completedTurn(Array.from(yield* Fiber.join(runtimeEventsFiber)));
2304+
assert.equal(payload.state, state);
2305+
if (errorMessage === undefined) {
2306+
assert.equal(payload.errorMessage, undefined);
2307+
} else {
2308+
assert.match(payload.errorMessage ?? "", errorMessage);
2309+
}
2310+
}).pipe(
2311+
Effect.provideService(Random.Random, makeDeterministicRandomService()),
2312+
Effect.provide(harness.layer),
2313+
);
2314+
},
2315+
);
2316+
2317+
it.effect("fails a usage-limited turn with the limit it parked on", () => {
2318+
const harness = makeHarness();
2319+
return Effect.gen(function* () {
2320+
const adapter = yield* ClaudeAdapter;
2321+
2322+
const runtimeEventsFiber = yield* adapter.streamEvents.pipe(
2323+
Stream.takeUntil((event) => event.type === "turn.completed"),
2324+
Stream.runCollect,
2325+
Effect.forkChild,
2326+
);
2327+
2328+
const session = yield* adapter.startSession({
2329+
threadId: THREAD_ID,
2330+
provider: ProviderDriverKind.make("claudeAgent"),
2331+
runtimeMode: "full-access",
2332+
});
2333+
yield* adapter.sendTurn({ threadId: session.threadId, input: "hello", attachments: [] });
2334+
2335+
const nowMs = yield* Clock.currentTimeMillis;
2336+
harness.query.emit({
2337+
type: "rate_limit_event",
2338+
rate_limit_info: {
2339+
status: "rejected",
2340+
rateLimitType: "five_hour",
2341+
resetsAt: Math.floor(nowMs / 1000) + 2 * 60 * 60,
2342+
},
2343+
session_id: "sdk-session-limit",
2344+
uuid: "rate-limit-rejected",
2345+
} as unknown as SDKMessage);
2346+
harness.query.emit({
2347+
type: "result",
2348+
subtype: "success",
2349+
is_error: false,
2350+
terminal_reason: "api_error",
2351+
errors: [],
2352+
session_id: "sdk-session-limit",
2353+
uuid: "result-limit",
2354+
} as unknown as SDKMessage);
2355+
2356+
const payload = completedTurn(Array.from(yield* Fiber.join(runtimeEventsFiber)));
2357+
assert.equal(payload.state, "failed");
2358+
assert.equal(
2359+
payload.errorMessage,
2360+
"Claude usage limit reached. Send the message again once the limit resets.",
2361+
);
2362+
}).pipe(
2363+
Effect.provideService(Random.Random, makeDeterministicRandomService()),
2364+
Effect.provide(harness.layer),
2365+
);
2366+
});
2367+
22022368
it.effect("fails a turn for every dead-turn terminal_reason", () => {
22032369
const reasons = [
22042370
"blocking_limit",

‎apps/server/src/provider/Layers/ClaudeAdapter.ts‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ import { resolveAttachmentPath } from "../../attachmentStore.ts";
8383
import { ServerConfig } from "../../config.ts";
8484
import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
8585
import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
86-
import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
86+
import { claudeSignedOutMessage, makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
8787
import { planClaudeSkillDispatch } from "../Drivers/ClaudeSkillDispatch.ts";
8888
import { discoverClaudeSkills } from "../Drivers/ClaudeSkills.ts";
8989
import { buildRuntimeInstructions } from "../RuntimeInstructions.ts";
@@ -159,6 +159,12 @@ interface ClaudeTurnState {
159159
compactedSinceLatestAssistantUsage: boolean;
160160
hasSubagents: boolean;
161161
nextSyntheticAssistantBlockIndex: number;
162+
/**
163+
* Real cause latched mid-turn (expired login, rejected usage window). The
164+
* CLI ends such turns with a generic API error, so the result handler
165+
* reports this instead.
166+
*/
167+
failureMessage: string | undefined;
162168
}
163169

164170
interface AssistantTextBlockState {
@@ -3184,6 +3190,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
31843190
compactedSinceLatestAssistantUsage: false,
31853191
hasSubagents: false,
31863192
nextSyntheticAssistantBlockIndex: -1,
3193+
failureMessage: undefined,
31873194
};
31883195
context.session = {
31893196
...context.session,
@@ -3242,6 +3249,11 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
32423249
}
32433250

32443251
if (context.turnState) {
3252+
// The CLI reports an expired login as a synthetic assistant message and
3253+
// then ends the turn as a plain API error, so latch the real cause here.
3254+
if (message.error === "authentication_failed") {
3255+
context.turnState.failureMessage = claudeSignedOutMessage(claudeSettings);
3256+
}
32453257
context.turnState.items.push(message.message);
32463258
if (
32473259
normalizeClaudeActiveTokenUsage(
@@ -3268,8 +3280,20 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
32683280
return;
32693281
}
32703282

3271-
const status = turnStatusFromResult(message);
3272-
const errorMessage = resultUserFacingError(message);
3283+
let status = turnStatusFromResult(message);
3284+
let errorMessage = resultUserFacingError(message);
3285+
3286+
// A turn that already reported its real cause ends as a generic API error,
3287+
// or as a success flagged is_error. Any other outcome names itself.
3288+
const failureMessage = context.turnState?.failureMessage;
3289+
if (
3290+
failureMessage !== undefined &&
3291+
(message.terminal_reason === "api_error" ||
3292+
(status === "completed" && message.is_error === true))
3293+
) {
3294+
status = "failed";
3295+
errorMessage = failureMessage;
3296+
}
32733297

32743298
if (status === "failed") {
32753299
yield* emitRuntimeError(context, errorMessage ?? "Claude turn failed.");
@@ -3898,6 +3922,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
38983922
names,
38993923
);
39003924
yield* emitRuntimeWarning(context, notice, rateLimitInfo);
3925+
// The CLI may still end the parked turn as a generic API error. The
3926+
// wait is left out: it was computed when the window rejected.
3927+
context.turnState.failureMessage =
3928+
"Claude usage limit reached. Send the message again once the limit resets.";
39013929
}
39023930
}
39033931
return;
@@ -4937,6 +4965,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
49374965
compactedSinceLatestAssistantUsage: false,
49384966
hasSubagents: false,
49394967
nextSyntheticAssistantBlockIndex: -1,
4968+
failureMessage: undefined,
49404969
};
49414970

49424971
const updatedAt = yield* nowIso;

0 commit comments

Comments
 (0)