Skip to content

Commit 76ff0eb

Browse files
JustYanniccclaude
andauthored
fix(server): recover after Claude capability probe failures (#21042)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 9494dba commit 76ff0eb

5 files changed

Lines changed: 260 additions & 20 deletions

File tree

‎apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,12 @@ import {
1313
import * as NodeFSP from "node:fs/promises";
1414
import * as NodeServices from "@effect/platform-node/NodeServices";
1515
import { assert, it } from "@effect/vitest";
16+
import * as Cause from "effect/Cause";
1617
import * as Effect from "effect/Effect";
1718
import * as FileSystem from "effect/FileSystem";
1819
import * as Path from "effect/Path";
1920
import * as Schema from "effect/Schema";
21+
import * as Result from "effect/Result";
2022

2123
import {
2224
buildClaudeCapabilitiesProbeQueryOptions,
@@ -367,6 +369,36 @@ it.effect("preserves initialized capabilities when optional usage times out", ()
367369
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
368370
);
369371

372+
it.effect("fails a hung initialization probe with a timeout", () =>
373+
Effect.gen(function* () {
374+
const initializationStarted = yield* Deferred.make<void>();
375+
const query = vi.spyOn(ClaudeSdk, "query").mockImplementation(
376+
() =>
377+
({
378+
initializationResult: () => {
379+
Deferred.doneUnsafe(initializationStarted, Effect.void);
380+
return new Promise(() => {});
381+
},
382+
usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: async () => ({
383+
rate_limits_available: true,
384+
rate_limits: {},
385+
}),
386+
}) as ReturnType<typeof ClaudeSdk.query>,
387+
);
388+
yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
389+
const probe = yield* probeClaudeCapabilities(
390+
decodeClaudeSettings({ binaryPath: "claude" }),
391+
).pipe(Effect.result, Effect.forkChild);
392+
393+
yield* Deferred.await(initializationStarted);
394+
yield* TestClock.adjust("25 seconds");
395+
const result = yield* Fiber.join(probe);
396+
397+
assert.isTrue(Result.isFailure(result));
398+
if (Result.isFailure(result)) assert.isTrue(Cause.isTimeoutError(result.failure));
399+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
400+
);
401+
370402
it.effect("asks for usage without the local transcript scan", () =>
371403
Effect.gen(function* () {
372404
let usageOptions: unknown;

‎apps/server/src/provider/ClaudeProvider.ts‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import {
55
type ServerProviderSlashCommand,
66
type ServerProviderResetCredits,
77
} from "@t3tools/contracts";
8+
import * as Cause from "effect/Cause";
89
import * as DateTime from "effect/DateTime";
910
import * as Effect from "effect/Effect";
1011
import * as FileSystem from "effect/FileSystem";
@@ -243,7 +244,7 @@ function nonEmptyProbeString(value: string): string | undefined {
243244
return candidate ? candidate : undefined;
244245
}
245246

246-
type ClaudeCapabilitiesProbe = {
247+
export type ClaudeCapabilitiesProbe = {
247248
readonly email: string | undefined;
248249
readonly workspaceId?: string | undefined;
249250
readonly subscriptionType: string | undefined;
@@ -419,11 +420,14 @@ const probeClaudeCapabilities = (
419420
if (!abort.signal.aborted) abort.abort();
420421
}),
421422
),
422-
Effect.result,
423-
Effect.map((result) => (Result.isSuccess(result) ? result.success : undefined)),
423+
Effect.tapError((error) =>
424+
Effect.logWarning("Claude capability probe failed.", { errorTag: error._tag }),
425+
),
424426
);
425427
};
426428

429+
type ClaudeCapabilitiesProbeError = Effect.Error<ReturnType<typeof probeClaudeCapabilities>>;
430+
427431
const runClaudeCommand = Effect.fn("runClaudeCommand")(function* (
428432
claudeSettings: ClaudeSettings,
429433
args: ReadonlyArray<string>,
@@ -450,7 +454,10 @@ export const probeClaudeWorkspaceSnapshot = Effect.fn("probeClaudeWorkspaceSnaps
450454
): Effect.fn.Return<ProviderWorkspaceSnapshot, never, FileSystem.FileSystem | Path.Path> {
451455
if (!claudeSettings.enabled) return machineSnapshot;
452456
const skills = yield* discoverClaudeSkills(claudeSettings, cwd, environment);
453-
const capabilities = yield* probeClaudeCapabilities(claudeSettings, environment, cwd, false);
457+
const probeResult = yield* probeClaudeCapabilities(claudeSettings, environment, cwd, false).pipe(
458+
Effect.result,
459+
);
460+
const capabilities = Result.isSuccess(probeResult) ? probeResult.success : undefined;
454461
return {
455462
...machineSnapshot,
456463
skills,
@@ -466,7 +473,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
466473
claudeSettings: ClaudeSettings,
467474
resolveCapabilities?: (
468475
claudeSettings: ClaudeSettings,
469-
) => Effect.Effect<ClaudeCapabilitiesProbe | undefined>,
476+
) => Effect.Effect<ClaudeCapabilitiesProbe | undefined, ClaudeCapabilitiesProbeError>,
470477
environment?: NodeJS.ProcessEnv,
471478
cwd?: string,
472479
modelCatalog: ClaudeModelCatalog = BUNDLED_CLAUDE_MODEL_CATALOG,
@@ -579,9 +586,13 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
579586
const updateRequiredModels = resolveClaudeUpdateRequiredModels(modelCatalog, parsedVersion);
580587
const versionUpgradeMessage = formatClaudeVersionUpgradeMessage(modelCatalog, parsedVersion);
581588

582-
const capabilities = resolveCapabilities
583-
? yield* resolveCapabilities(claudeSettings).pipe(Effect.orElseSucceed(() => undefined))
589+
const probeResult = resolveCapabilities
590+
? yield* resolveCapabilities(claudeSettings).pipe(Effect.result)
584591
: undefined;
592+
const capabilities =
593+
probeResult && Result.isSuccess(probeResult) ? probeResult.success : undefined;
594+
const probeFailure =
595+
probeResult && Result.isFailure(probeResult) ? probeResult.failure : undefined;
585596
const skills = yield* discoverClaudeSkills(claudeSettings, cwd, resolvedEnvironment);
586597
const slashCommands = [COMPACT_SLASH_COMMAND, ...(capabilities?.slashCommands ?? [])];
587598
const dedupedSlashCommands = dedupeSlashCommands(slashCommands);
@@ -600,7 +611,11 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
600611
version: parsedVersion,
601612
status: "warning",
602613
auth: { status: "unknown" },
603-
message: "Could not verify Claude authentication status from initialization result.",
614+
message: probeFailure
615+
? Cause.isTimeoutError(probeFailure)
616+
? `Timed out after ${CAPABILITIES_PROBE_TIMEOUT_MS / 1_000}s while checking Claude account status.`
617+
: "Claude Agent CLI failed while checking account status."
618+
: "Could not verify Claude authentication status from initialization result.",
604619
},
605620
});
606621
}

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

Lines changed: 54 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@ import * as Cache from "effect/Cache";
33
import * as Duration from "effect/Duration";
44
import * as Crypto from "effect/Crypto";
55
import * as Effect from "effect/Effect";
6+
import * as Exit from "effect/Exit";
67
import * as FileSystem from "effect/FileSystem";
78
import * as Path from "effect/Path";
9+
import * as Ref from "effect/Ref";
810
import * as Schema from "effect/Schema";
911
import { HttpClient } from "effect/http";
1012
import { ChildProcessSpawner } from "effect/process";
@@ -29,6 +31,7 @@ import {
2931
makePendingClaudeProvider,
3032
probeClaudeCapabilities,
3133
probeClaudeWorkspaceSnapshot,
34+
type ClaudeCapabilitiesProbe,
3235
} from "../ClaudeProvider.ts";
3336
import { makeManagedServerProvider } from "@t3tools/provider-core/server/managedProvider";
3437
import * as ModelCatalog from "@t3tools/provider-core/server/ModelCatalog";
@@ -63,6 +66,12 @@ const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
6366
const DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
6467
const CAPABILITIES_PROBE_TTL = Duration.minutes(5);
6568

69+
const withoutUsage = (capabilities: ClaudeCapabilitiesProbe): ClaudeCapabilitiesProbe => {
70+
const result = { ...capabilities };
71+
delete result.usage;
72+
return result;
73+
};
74+
6675
function isClaudeNativeCommandPath(commandPath: string): boolean {
6776
const normalized = normalizeCommandPath(commandPath);
6877
return (
@@ -187,34 +196,67 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
187196

188197
// Per-instance capabilities cache: keyed on binary + resolved HOME so
189198
// account-specific probes never share auth metadata across instances.
190-
const capabilitiesProbeCache = yield* Cache.make({
191-
capacity: 1,
192-
timeToLive: CAPABILITIES_PROBE_TTL,
193-
lookup: () =>
194-
Effect.all([
195-
probeClaudeCapabilities(effectiveConfig, processEnv, stateDir),
196-
ClaudeResetCredits.readClaudeOrganizationId(accountConfigPath),
197-
]).pipe(
198-
Effect.map(([capabilities, workspaceId]) =>
199-
capabilities && workspaceId ? { ...capabilities, workspaceId } : capabilities,
199+
// A transient miss may reuse the last account once, but its usage windows keep their age.
200+
const lastGoodCapabilities = yield* Ref.make<ClaudeCapabilitiesProbe | undefined>(undefined);
201+
const capabilitiesProbeCache = yield* Cache.makeWith(
202+
() =>
203+
probeClaudeCapabilities(effectiveConfig, processEnv, stateDir).pipe(
204+
Effect.flatMap((capabilities) =>
205+
ClaudeResetCredits.readClaudeOrganizationId(accountConfigPath).pipe(
206+
Effect.map((workspaceId) => ({
207+
_tag: "fresh" as const,
208+
capabilities:
209+
workspaceId === undefined ? capabilities : { ...capabilities, workspaceId },
210+
})),
211+
),
212+
),
213+
Effect.tap(({ capabilities }) => Ref.set(lastGoodCapabilities, capabilities)),
214+
Effect.catch((error) =>
215+
Ref.getAndSet(lastGoodCapabilities, undefined).pipe(
216+
Effect.flatMap((capabilities) =>
217+
capabilities === undefined
218+
? Effect.fail(error)
219+
: ClaudeResetCredits.readClaudeOrganizationId(accountConfigPath).pipe(
220+
Effect.flatMap((workspaceId) =>
221+
workspaceId === capabilities.workspaceId
222+
? Effect.succeed({
223+
_tag: "fallback" as const,
224+
capabilities: withoutUsage(capabilities),
225+
})
226+
: Effect.fail(error),
227+
),
228+
),
229+
),
230+
),
200231
),
201232
Effect.provideService(FileSystem.FileSystem, fileSystem),
202233
Effect.provideService(Path.Path, path),
203234
),
204-
});
235+
{
236+
capacity: 1,
237+
timeToLive: (exit) =>
238+
// Only a fresh probe earns the TTL; a failure or its fallback retries on the next check.
239+
Exit.isSuccess(exit) && exit.value._tag === "fresh"
240+
? CAPABILITIES_PROBE_TTL
241+
: Duration.zero,
242+
},
243+
);
205244
const capabilitiesCacheKey = yield* makeClaudeCapabilitiesCacheKey(
206245
effectiveConfig,
207246
stateDir,
208247
processEnv,
209248
);
249+
const resolveCapabilities = Cache.get(capabilitiesProbeCache, capabilitiesCacheKey).pipe(
250+
Effect.map((result) => result.capabilities),
251+
);
210252

211253
const checkProvider = catalogService.refreshInBackground.pipe(
212254
Effect.andThen(
213255
modelCatalog.pipe(
214256
Effect.flatMap((catalog) =>
215257
checkClaudeProviderStatus(
216258
effectiveConfig,
217-
() => Cache.get(capabilitiesProbeCache, capabilitiesCacheKey),
259+
() => resolveCapabilities,
218260
processEnv,
219261
stateDir,
220262
catalog,

0 commit comments

Comments
 (0)