anthropics / anthropics/claude-agent-sdk-typescript

Fast Mode Unavailable via SDK — Requires Native Bun Binary

Đang mở
#216 1 bình luận 4 reaction 0 người được giao Xem trên GitHub
bug enhancement
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á.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.