anthropics / anthropics/claude-agent-sdk-typescript
Fast Mode Unavailable via SDK — Requires Native Bun Binary
- Ngôn ngữ chính
- Shell
- Star
- 1.8k
- Fork
- 226
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
## Summary
Fast mode (`/fast`) cannot function when using the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) from a Node.js host. The SDK correctly accepts the `settings.fastMode` option but the underlying native streaming binary is only available in the Bun-compiled CLI product, not in the npm package.
## Environment
- **SDK:** `@anthropic-ai/claude-agent-sdk` (npm)
- **Affected models:** Claude Opus 4.6, Claude Sonnet 4.6
## Root Cause
The Claude Code CLI is compiled as a **Bun standalone binary** with a native Rust streaming component embedded via `Bun.embeddedFiles`. This native component is what provides the faster token output that fast mode advertises.
The SDK checks for the native binary with:
```js
function e5() {
return typeof Bun < "u" && Array.isArray(Bun.embeddedFiles) && Bun.embeddedFiles.length > 0;
}
```
Since Node.js consumers of the SDK runs outside of Bun, `typeof Bun` is always `"undefined"`, so `e5()` always returns `false`.
### Execution Flow
1. `settings.fastMode = true` is passed to `query()` — SDK receives it correctly
2. SDK calls its availability check → native binary not found (not Bun)
3. Server-side feature flag `tengu_marble_sandcastle` is enabled → requires native binary
4. SDK emits a `[WARN] Fast mode requires the native binary` stderr warning
5. Falls back silently to regular Opus 4.6
## Impact
- **No fast mode for SDK consumers.** Any application using the npm package (`@anthropic-ai/claude-agent-sdk`) in Node.js, Deno, or any non-Bun runtime cannot use fast mode. The native streaming binary only ships with the Bun-compiled CLI distribution.
- **Silent degradation.** The SDK accepts `fastMode: true` without error and falls back to the standard model. Users toggling fast mode in a UI get no indication it isn't active (aside from a stderr warning that may not be surfaced).
- **Misleading API surface.** `Options.settings.fastMode` is exposed in the SDK's TypeScript types (`sdk.d.ts`), suggesting it's a supported feature for npm consumers.
## Expected Behavior
One of:
1. **Ship the native streaming component in the npm package** so SDK consumers can use fast mode regardless of runtime.
2. **Expose an explicit capability check** (e.g., `sdk.isFastModeAvailable()`) so consumers can detect unavailability before presenting the option to users.
3. **Document the limitation** clearly in the SDK README / TypeScript docs that `fastMode` only works when running inside the Bun-compiled CLI binary.
## Reproduction
```ts
import { query } from "@anthropic-ai/claude-agent-sdk";
// Run this in Node.js (not Bun)
const result = query({
prompt: "Hello",
settings: { fastMode: true },
// ... other options
});
// Observe: [WARN] Fast mode requires the native binary
// Result: standard Opus 4.6 response, not fast mode
```
## References
- SDK source: `node_modules/@anthropic-ai/claude-agent-sdk/cli.js` — `e5()` function (native binary check), `vj6()` (Bun runtime detection)
- SDK types: `node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts` — `Settings.fastMode` property
- Feature flag: `tengu_marble_sandcastle` (server-side, gates native binary requirement)
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Đánh giá
Issue này chưa được đánh giá.