Skip to content

Commit 26a02ed

Browse files
Yuruzuuclaude
andcommitted
perf(claude): composer stops starting the CLI when a folder's commands can't have changed
Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 30654b3 commit 26a02ed

4 files changed

Lines changed: 493 additions & 17 deletions

File tree

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

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,13 @@ import { ClaudeSettings, type ServerProvider } from "@t3tools/contracts";
44
import { vi } from "vite-plus/test";
55
import { assert, it } from "@effect/vitest";
66
import * as Effect from "effect/Effect";
7+
import * as FileSystem from "effect/FileSystem";
8+
import * as Path from "effect/Path";
79
import * as Schema from "effect/Schema";
810

911
import {
1012
buildClaudeCapabilitiesProbeQueryOptions,
13+
makeClaudeWorkspaceCommands,
1114
probeClaudeWorkspaceSnapshot,
1215
} from "./ClaudeProvider.ts";
1316

@@ -37,7 +40,193 @@ it.effect("reports a deleted worktree's scan as finished, not pending", () =>
3740
{ skills: [], slashCommands: [] } as unknown as ServerProvider,
3841
"/nonexistent/t3-deleted-worktree",
3942
{ HOME: "/nonexistent/t3-home" },
43+
() => Effect.die("a deleted worktree must not start the CLI"),
4044
);
4145
assert.strictEqual(snapshot.slashCommandsPending, false);
4246
}).pipe(Effect.provide(NodeServices.layer)),
4347
);
48+
49+
const makeCommandSourcesFixture = Effect.gen(function* () {
50+
const fileSystem = yield* FileSystem.FileSystem;
51+
const path = yield* Path.Path;
52+
const root = yield* fileSystem.realPath(yield* fileSystem.makeTempDirectoryScoped());
53+
const write = Effect.fnUntraced(function* (file: string, contents = "contents") {
54+
yield* fileSystem.makeDirectory(path.dirname(file), { recursive: true });
55+
yield* fileSystem.writeFileString(file, contents);
56+
});
57+
// A linked worktree, as `git worktree add` lays it out, with the cwd below its root.
58+
const main = path.join(root, "main");
59+
const worktree = path.join(root, "worktree");
60+
const gitDirectory = path.join(main, ".git", "worktrees", "worktree");
61+
const cwd = path.join(worktree, "packages", "app");
62+
yield* write(path.join(worktree, ".git"), `gitdir: ${gitDirectory}\n`);
63+
yield* write(path.join(gitDirectory, "commondir"), "../..\n");
64+
yield* write(path.join(gitDirectory, "gitdir"), `${path.join(worktree, ".git")}\n`);
65+
yield* fileSystem.makeDirectory(cwd, { recursive: true });
66+
67+
let probes = 0;
68+
let failing = false;
69+
const config = path.join(root, "config");
70+
const makeCommands = (environment: NodeJS.ProcessEnv = {}) =>
71+
makeClaudeWorkspaceCommands({ homePath: config }, environment, () =>
72+
Effect.suspend(() => {
73+
probes += 1;
74+
return failing ? Effect.fail("probe failed") : Effect.succeed([{ name: "review" }]);
75+
}),
76+
);
77+
return {
78+
path,
79+
write,
80+
root,
81+
main,
82+
worktree,
83+
cwd,
84+
config,
85+
makeCommands,
86+
probes: () => probes,
87+
failNextProbes: (value: boolean) => {
88+
failing = value;
89+
},
90+
};
91+
});
92+
93+
const machine = { version: "1.0.0", auth: { status: "authenticated" }, slashCommands: [] } as const;
94+
95+
it.effect("starts the CLI again only when a source of its command list changes", () =>
96+
Effect.gen(function* () {
97+
const { path, write, main, worktree, cwd, config, makeCommands, probes } =
98+
yield* makeCommandSourcesFixture;
99+
const commands = yield* makeCommands();
100+
101+
yield* commands.get(machine, cwd);
102+
yield* commands.get(machine, cwd);
103+
assert.strictEqual(probes(), 1);
104+
105+
// Each of these changed real CLI output or feeds it; see fingerprintClaudeCommandSources.
106+
for (const source of [
107+
path.join(config, "commands", "nested", "a.md"),
108+
path.join(config, "skills", "a", "SKILL.md"),
109+
path.join(config, "workflows", "a.js"),
110+
path.join(config, "synced", "account", "a", "SKILL.md"),
111+
path.join(config, "settings.json"),
112+
path.join(config, "remote-settings.json"),
113+
path.join(config, "plugins", "installed_plugins.json"),
114+
path.join(config, "plugins", "synced", "account", ".marketplace-a.json"),
115+
path.join(config, "plugins", "cache", "market", "plugin", "1.0.0", "commands", "a.md"),
116+
path.join(config, "plugins", "cache", "market", "plugin", "1.0.0", "skills", "store", "a.md"),
117+
path.join(cwd, ".claude", "commands", "a.md"),
118+
path.join(cwd, ".claude", "skills", "a", "SKILL.md"),
119+
path.join(cwd, ".claude", "workflows", "a.js"),
120+
path.join(cwd, ".claude", "settings.json"),
121+
path.join(cwd, ".claude", "settings.local.json"),
122+
path.join(worktree, ".claude", "commands", "a.md"),
123+
path.join(main, ".claude", "skills", "a", "SKILL.md"),
124+
]) {
125+
const before = probes();
126+
yield* write(
127+
source,
128+
source.endsWith("installed_plugins.json") ? '{"plugins":{}}' : "contents",
129+
);
130+
yield* commands.get(machine, cwd);
131+
assert.strictEqual(probes(), before + 1, `${source} should start the CLI`);
132+
yield* commands.get(machine, cwd);
133+
assert.strictEqual(probes(), before + 1, `${source} should settle`);
134+
}
135+
136+
const edited = path.join(cwd, ".claude", "commands", "a.md");
137+
const beforeEdit = probes();
138+
yield* write(edited, "edited description");
139+
yield* commands.get(machine, cwd);
140+
assert.strictEqual(probes(), beforeEdit + 1);
141+
142+
const beforeUnrelated = probes();
143+
yield* write(path.join(cwd, ".claude", "agents", "a.md"));
144+
yield* write(path.join(config, "plugins", "marketplaces", "market", "README.md"));
145+
yield* write(path.join(config, "plugins", "store", "runtime-state.json"));
146+
yield* write(path.join(config, "plugins", "synced", "account", ".last-complete-round"));
147+
yield* write(path.join(config, "plugins", "synced", "account", ".marketplaces.json"));
148+
yield* commands.get(machine, cwd);
149+
assert.strictEqual(probes(), beforeUnrelated);
150+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
151+
);
152+
153+
it.effect("starts the CLI again when the health check's view of it changes", () =>
154+
Effect.gen(function* () {
155+
const { cwd, makeCommands, probes } = yield* makeCommandSourcesFixture;
156+
const commands = yield* makeCommands();
157+
yield* commands.get(machine, cwd);
158+
yield* commands.get({ ...machine, version: "1.0.1" }, cwd);
159+
assert.strictEqual(probes(), 2);
160+
yield* commands.get({ ...machine, auth: { status: "unauthenticated" } }, cwd);
161+
assert.strictEqual(probes(), 3);
162+
yield* commands.get({ ...machine, slashCommands: [{ name: "upgrade" }] }, cwd);
163+
assert.strictEqual(probes(), 4);
164+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
165+
);
166+
167+
it.effect("keeps folders apart, retries failures, and forgets on invalidate", () =>
168+
Effect.gen(function* () {
169+
const { cwd, worktree, makeCommands, probes, failNextProbes } =
170+
yield* makeCommandSourcesFixture;
171+
const commands = yield* makeCommands();
172+
173+
failNextProbes(true);
174+
yield* commands.get(machine, cwd).pipe(Effect.result);
175+
failNextProbes(false);
176+
yield* commands.get(machine, cwd);
177+
assert.strictEqual(probes(), 2);
178+
179+
yield* commands.get(machine, worktree);
180+
assert.strictEqual(probes(), 3);
181+
182+
yield* commands.invalidate;
183+
yield* commands.get(machine, cwd);
184+
assert.strictEqual(probes(), 4);
185+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
186+
);
187+
188+
it.effect("always starts the CLI when its sources cannot be vouched for", () =>
189+
Effect.gen(function* () {
190+
const { path, write, root, cwd, config, makeCommands, probes } =
191+
yield* makeCommandSourcesFixture;
192+
const probesTwice = (commands: Effect.Success<ReturnType<typeof makeCommands>>) =>
193+
Effect.gen(function* () {
194+
const before = probes();
195+
yield* commands.get(machine, cwd);
196+
yield* commands.get(machine, cwd);
197+
assert.strictEqual(probes(), before + 2);
198+
});
199+
200+
yield* probesTwice(yield* makeCommands({ CLAUDE_CODE_PLUGIN_DIRS: "/elsewhere" }));
201+
202+
const commands = yield* makeCommands();
203+
const settings = path.join(cwd, ".claude", "settings.json");
204+
yield* write(settings, '{"env":{"CLAUDE_CODE_PLUGIN_SEED_DIR":"/elsewhere"}}');
205+
yield* probesTwice(commands);
206+
yield* write(settings, "{}");
207+
208+
const installed = path.join(config, "plugins", "installed_plugins.json");
209+
yield* write(
210+
installed,
211+
JSON.stringify({ plugins: { "a@b": [{ installPath: path.join(root, "elsewhere") }] } }),
212+
);
213+
yield* probesTwice(commands);
214+
yield* write(installed, "not json");
215+
yield* probesTwice(commands);
216+
yield* write(installed, '{"plugins":{}}');
217+
218+
const marketplaces = path.join(config, "plugins", "known_marketplaces.json");
219+
yield* write(marketplaces, '{"local":{"source":{"source":"directory","path":"/elsewhere"}}}');
220+
yield* probesTwice(commands);
221+
yield* write(marketplaces, '{"remote":{"source":{"source":"github","repo":"a/b"}}}');
222+
const beforeRemote = probes();
223+
yield* commands.get(machine, cwd);
224+
yield* commands.get(machine, cwd);
225+
assert.strictEqual(probes(), beforeRemote + 1);
226+
227+
for (let index = 0; index <= 2_000; index++) {
228+
yield* write(path.join(cwd, ".claude", "skills", `${index}.md`));
229+
}
230+
yield* probesTwice(commands);
231+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
232+
);

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

Lines changed: 59 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,12 @@ import {
55
type ServerProviderSlashCommand,
66
type ServerProviderResetCredits,
77
} from "@t3tools/contracts";
8+
import * as Cache from "effect/Cache";
89
import * as Cause from "effect/Cause";
910
import * as DateTime from "effect/DateTime";
11+
import * as Duration from "effect/Duration";
1012
import * as Effect from "effect/Effect";
13+
import * as Exit from "effect/Exit";
1114
import * as FileSystem from "effect/FileSystem";
1215
import * as Option from "effect/Option";
1316
import * as Path from "effect/Path";
@@ -37,7 +40,11 @@ import {
3740
} from "@t3tools/provider-core/server/snapshotProbe";
3841
import { resolveClaudeSdkExecutablePath } from "./Drivers/ClaudeExecutable.ts";
3942
import { hasClaudeManagedMcpConfig, makeClaudeEnvironment } from "./Drivers/ClaudeHome.ts";
40-
import { discoverClaudeSkills, readClaudeSettingsEnv } from "./Drivers/ClaudeSkills.ts";
43+
import {
44+
discoverClaudeSkills,
45+
fingerprintClaudeCommandSources,
46+
readClaudeSettingsEnv,
47+
} from "./Drivers/ClaudeSkills.ts";
4148
import type { ProviderWorkspaceSnapshot } from "@t3tools/provider-core/server/driver";
4249
import { makeUnavailableUsageLimits } from "@t3tools/provider-core/server/usageLimits";
4350
import {
@@ -421,30 +428,71 @@ const runClaudeCommand = Effect.fn("runClaudeCommand")(function* (
421428
return yield* spawnAndCollect(claudeSettings.binaryPath, command);
422429
});
423430

424-
export const probeClaudeWorkspaceSnapshot = Effect.fn("probeClaudeWorkspaceSnapshot")(function* (
431+
// Twice the registry's snapshot cap, so a folder it evicts can return without a spawn.
432+
const WORKSPACE_COMMANDS_CAPACITY = 32;
433+
// Bounds staleness from anything the fingerprint cannot see.
434+
const WORKSPACE_COMMANDS_MAX_AGE = Duration.hours(1);
435+
436+
/** Starting the CLI per folder is costly and its answer rarely changes, so reuse it until its sources do. */
437+
export const makeClaudeWorkspaceCommands = Effect.fn("makeClaudeWorkspaceCommands")(function* <E>(
438+
claudeSettings: Pick<ClaudeSettings, "homePath">,
439+
environment: NodeJS.ProcessEnv,
440+
probeCommands: (cwd: string) => Effect.Effect<ReadonlyArray<ServerProviderSlashCommand>, E>,
441+
) {
442+
const cache = yield* Cache.makeWith(
443+
(key: { readonly cwd: string; readonly fingerprint: string }) => probeCommands(key.cwd),
444+
{
445+
capacity: WORKSPACE_COMMANDS_CAPACITY,
446+
timeToLive: (exit) => (Exit.isSuccess(exit) ? WORKSPACE_COMMANDS_MAX_AGE : Duration.zero),
447+
},
448+
);
449+
return {
450+
invalidate: Cache.invalidateAll(cache),
451+
get: Effect.fn("ClaudeWorkspaceCommands.get")(function* (
452+
machineSnapshot: Pick<ServerProvider, "version" | "auth" | "slashCommands">,
453+
cwd: string,
454+
) {
455+
// Taken before probing, so an edit during the probe forces another one next time.
456+
const fingerprint = yield* fingerprintClaudeCommandSources(claudeSettings, cwd, environment, [
457+
machineSnapshot.version,
458+
machineSnapshot.auth,
459+
machineSnapshot.slashCommands,
460+
]);
461+
return yield* fingerprint === undefined
462+
? probeCommands(cwd)
463+
: Cache.get(cache, { cwd, fingerprint });
464+
}),
465+
};
466+
});
467+
468+
export const probeClaudeWorkspaceSnapshot = Effect.fn("probeClaudeWorkspaceSnapshot")(function* <E>(
425469
claudeSettings: ClaudeSettings,
426470
machineSnapshot: ServerProvider,
427471
cwd: string,
428-
environment?: NodeJS.ProcessEnv,
472+
environment: NodeJS.ProcessEnv | undefined,
473+
resolveCommands: (
474+
machineSnapshot: ServerProvider,
475+
cwd: string,
476+
) => Effect.Effect<
477+
ReadonlyArray<ServerProviderSlashCommand>,
478+
E,
479+
FileSystem.FileSystem | Path.Path
480+
>,
429481
): Effect.fn.Return<ProviderWorkspaceSnapshot, never, FileSystem.FileSystem | Path.Path> {
430482
if (!claudeSettings.enabled) return machineSnapshot;
431483
const skills = yield* discoverClaudeSkills(claudeSettings, cwd, environment);
432484
const fileSystem = yield* FileSystem.FileSystem;
433485
// A deleted worktree can never answer the probe. Pending would make clients rescan it forever.
434486
const cwdExists = yield* fileSystem.exists(cwd).pipe(Effect.orElseSucceed(() => true));
435487
const probeResult = cwdExists
436-
? yield* probeClaudeCapabilities(claudeSettings, environment, cwd, false).pipe(Effect.result)
488+
? yield* resolveCommands(machineSnapshot, cwd).pipe(Effect.result)
437489
: undefined;
438-
const capabilities =
439-
probeResult && Result.isSuccess(probeResult) ? probeResult.success : undefined;
490+
const commands = probeResult && Result.isSuccess(probeResult) ? probeResult.success : undefined;
440491
return {
441492
...machineSnapshot,
442493
skills,
443-
slashCommands: dedupeSlashCommands([
444-
COMPACT_SLASH_COMMAND,
445-
...(capabilities?.slashCommands ?? []),
446-
]),
447-
slashCommandsPending: cwdExists && !capabilities,
494+
slashCommands: dedupeSlashCommands([COMPACT_SLASH_COMMAND, ...(commands ?? [])]),
495+
slashCommandsPending: cwdExists && !commands,
448496
};
449497
});
450498

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

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ import {
3030
checkClaudeProviderStatus,
3131
makePendingClaudeProvider,
3232
probeClaudeCapabilities,
33+
makeClaudeWorkspaceCommands,
3334
probeClaudeWorkspaceSnapshot,
3435
type ClaudeCapabilitiesProbe,
3536
} from "../ClaudeProvider.ts";
@@ -385,6 +386,17 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
385386
),
386387
);
387388

389+
const workspaceCommands = yield* makeClaudeWorkspaceCommands(
390+
effectiveConfig,
391+
processEnv,
392+
(cwd) =>
393+
probeClaudeCapabilities(effectiveConfig, processEnv, cwd, false).pipe(
394+
Effect.map((capabilities) => capabilities.slashCommands),
395+
Effect.provideService(FileSystem.FileSystem, fileSystem),
396+
Effect.provideService(Path.Path, path),
397+
),
398+
);
399+
388400
return {
389401
instanceId,
390402
driverKind: DRIVER_KIND,
@@ -396,11 +408,19 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
396408
accentColor,
397409
enabled,
398410
snapshot,
399-
invalidateCaches: Cache.invalidateAll(capabilitiesProbeCache),
411+
invalidateCaches: Cache.invalidateAll(capabilitiesProbeCache).pipe(
412+
Effect.andThen(workspaceCommands.invalidate),
413+
),
400414
snapshotForCwd: (cwd: string) =>
401415
snapshot.getSnapshot.pipe(
402416
Effect.flatMap((machineSnapshot) =>
403-
probeClaudeWorkspaceSnapshot(effectiveConfig, machineSnapshot, cwd, processEnv),
417+
probeClaudeWorkspaceSnapshot(
418+
effectiveConfig,
419+
machineSnapshot,
420+
cwd,
421+
processEnv,
422+
workspaceCommands.get,
423+
),
404424
),
405425
Effect.provideService(FileSystem.FileSystem, fileSystem),
406426
Effect.provideService(Path.Path, path),

0 commit comments

Comments
 (0)