@warlock.js/ai-anthropic 5.29.0 → 5.31.0

package/esm/model.d.mts

@@ -0,0 +1,322 @@
+import { AnthropicModelConfig } from "./config.type.mjs";
+import { AnthropicNonStreamingRequest, AnthropicRequest, AnthropicRequestOptions, AnthropicStreamingRequest } from "./request.type.mjs";
+import Anthropic from "@anthropic-ai/sdk";
+import { Message, ModelCallOptions, ModelCapabilities, ModelContract, ModelPricing, ModelResponse, ModelStreamChunk } from "@warlock.js/ai";
+
+//#region ../../packages/ai-anthropic/src/model.d.ts
+/**
+ * Anthropic-backed implementation of `ModelContract`.
+ *
+ * **Role.** The provider-facing bridge between the vendor-neutral
+ * `@warlock.js/ai` agent runtime and the official `@anthropic-ai/sdk`
+ * Messages API. Agents, workflows, and supervisors never talk to
+ * Anthropic directly — they hold a `ModelContract`, and this class is
+ * what makes that contract concrete for Claude models.
+ *
+ * **Responsibility.**
+ * - Owns: a long-lived `Anthropic` client + frozen `ModelConfig`
+ *   (name, temperature, maxTokens) used as defaults for every call.
+ * - Owns: translating vendor-neutral `Message[]` / `ToolConfig[]` into
+ *   Anthropic wire shapes (system hoisting, `tool_use` / `tool_result`
+ *   blocks) on the way out, and translating Anthropic's content-block
+ *   response (text, tool calls, stop reason, usage) back into the
+ *   neutral shapes on the way in.
+ * - Does NOT own: dispatching tools, deciding whether to loop, tracking
+ *   conversation history, or retrying on failure — those are agent
+ *   concerns. The model is a stateless (per-call) protocol adapter.
+ *
+ * Because it holds a live client and shared defaults, it is modeled as
+ * a class (see §4.2 of code-style.md — "long-lived state across
+ * calls").
+ *
+ * @example
+ * import Anthropic from "@anthropic-ai/sdk";
+ * const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ * const model = new AnthropicModel(client, { name: "claude-sonnet-4-6" });
+ *
+ * const myAgent = agent({
+ *   model,
+ *   systemPrompt: "You are a helpful assistant.",
+ *   tools: [searchTool],
+ * });
+ *
+ * const result = await myAgent.execute("Summarize today's news.");
+ */
+declare class AnthropicModel implements ModelContract {
+  readonly name: string;
+  readonly provider: string;
+  readonly capabilities: ModelCapabilities;
+  readonly pricing?: ModelPricing;
+  private readonly client;
+  private readonly config;
+  private readonly thinkingMode;
+  /** Documented max output tokens of this model, when known. Sizes the default `max_tokens`. */
+  private readonly maxOutputTokens?;
+  private readonly preservedThinking;
+  private readonly logger;
+  constructor(client: Anthropic, config: AnthropicModelConfig, provider?: string);
+  /**
+   * Single-shot completion. Sends the full message list to the Messages
+   * endpoint, waits for the terminal response, and reshapes it into a
+   * vendor-neutral `ModelResponse`. Per-call `options` override the
+   * instance's `ModelConfig` defaults for this call only.
+   */
+  complete(messages: Message[], options?: ModelCallOptions): Promise<ModelResponse>;
+  /** Build a detached request snapshot without sending it to Anthropic. */
+  buildRequest(messages: Message[], options: ModelCallOptions & {
+    stream: true;
+  }): AnthropicStreamingRequest;
+  buildRequest(messages: Message[], options?: ModelCallOptions & {
+    stream?: false;
+  }): AnthropicNonStreamingRequest;
+  buildRequest(messages: Message[], options?: ModelCallOptions & {
+    stream?: boolean;
+  }): AnthropicRequest;
+  /**
+   * `buildRequest()` for the adapter's own calls: a build failure (a reserved
+   * body key, a `providerOptions.anthropic.body` value `structuredClone`
+   * cannot copy) is logged like a send failure and rejects as an `AIError`.
+   * Errors that are not already an `AIError` become an `InvalidRequestError`,
+   * since nothing reached Anthropic and retrying cannot help.
+   */
+  private buildLoggedRequest;
+  /** Send a built request without rebuilding its body or applying model defaults. */
+  send(request: AnthropicNonStreamingRequest, options?: AnthropicRequestOptions): Promise<ModelResponse>;
+  send(request: AnthropicStreamingRequest, options?: AnthropicRequestOptions): AsyncIterable<ModelStreamChunk>;
+  send(request: AnthropicRequest, options?: AnthropicRequestOptions): Promise<ModelResponse> | AsyncIterable<ModelStreamChunk>;
+  private completeRequest;
+  /**
+   * Count the input tokens a request would use, through Anthropic's
+   * `messages.countTokens` endpoint (a network call; no tokens are
+   * generated or billed as output). Takes the same messages and options
+   * as `complete()` — system prompt, tools, thinking and
+   * `providerOptions.anthropic.betas` are counted exactly as they would be
+   * sent. For an offline estimate use `AnthropicSDK.count()`.
+   *
+   * @example
+   * const tokens = await model.countTokens(messages, { tools });
+   */
+  countTokens(messages: Message[], options?: ModelCallOptions): Promise<number>;
+  /**
+   * Incremental streaming completion. Yields neutral `ModelStreamChunk`s
+   * — `delta` for text tokens, `tool-call` once a `tool_use` block's
+   * arguments have fully accumulated, and a terminal `done` carrying the
+   * final finish reason + usage totals. Callers consume it with
+   * `for await`.
+   *
+   * With `options.streamChunks` it also yields `reasoning` for every
+   * non-empty `thinking_delta`, `tool-args` for every `input_json_delta`
+   * of a client `tool_use` block, and `usage` after `message_start` and
+   * each `message_delta` (whose counts are cumulative).
+   */
+  stream(messages: Message[], options?: ModelCallOptions): AsyncIterable<ModelStreamChunk>;
+  private streamRequest;
+  /**
+   * Fold one stream event into the per-index block accumulator. Unknown
+   * block and delta types (beta `compaction`, future additions) are kept
+   * as their start payload plus whatever their delta carries, so they
+   * round-trip without the adapter knowing their shape.
+   */
+  private trackStreamedBlock;
+  /** Close the accumulated stream blocks into an ordered content array. */
+  private finishStreamedBlocks;
+  /**
+   * Send a request through the SDK. With `providerOptions.anthropic.betas`
+   * the call goes to `client.beta.messages` (which takes the `betas` list
+   * and the beta-only body fields); otherwise to `client.messages`. The
+   * cancellation signal rides in the request options, as before.
+   */
+  private dispatch;
+  /**
+   * The full request body and the beta flags it needs: the adapter-built
+   * params, then `thinking.display` when thinking is sent on an adaptive
+   * model, the typed `thinkingBlockBinding`, `contextManagement` and
+   * `serverCompaction` options, then `providerOptions.anthropic.body`
+   * merged last (caller fields win). The body may add fields the adapter
+   * does not build (`fallbacks`, …) but may not replace the conversation or
+   * the model — see {@link RESERVED_BODY_FIELDS}.
+   */
+  private buildBody;
+  /**
+   * Set `thinking.block_binding.prefix_mismatch_behavior`. It rides on
+   * adaptive or budget (`enabled`) thinking. A model that runs adaptive
+   * thinking when `thinking` is omitted (every preserved-thinking model) gets
+   * an explicit `{ type: "adaptive" }`, which is the same request. Any other
+   * shape (`between_tools`, `disabled`) takes no extra field, so the option
+   * is skipped with a debug log.
+   */
+  private applyBlockBinding;
+  /**
+   * Assemble the Anthropic request body shared by `complete()` and
+   * `stream()` (each adds its own `stream` literal so the SDK's create
+   * overload resolves to the right return type). Hoists the system
+   * prompt out of `messages`, resolves `max_tokens` (required by
+   * Anthropic) with the documented default, and conditionally attaches
+   * temperature, tools, native structured output, extended thinking
+   * (`reasoning`), and automatic or explicit prompt-cache control.
+   * Temperature is dropped when thinking is enabled, since Anthropic
+   * rejects the two together, and always for adaptive-mode models, which
+   * reject any explicit temperature (see `acceptsTemperature`).
+   */
+  private buildParams;
+  /**
+   * The `max_tokens` sent when neither the call nor the model config sets
+   * `maxTokens`:
+   *
+   * - streaming: the model's documented max output, or
+   *   `DEFAULT_MAX_TOKENS` (16384) for an unknown id;
+   * - non-streaming: `DEFAULT_MAX_TOKENS`, capped by the model's max output
+   *   (the SDK requires streaming for larger non-streaming requests unless
+   *   the client sets a `timeout`; see `DEFAULT_MAX_TOKENS`).
+   *
+   * With thinking on, the value is raised to at least the thinking budget
+   * plus `MIN_ANSWER_TOKENS`, and never exceeds the model's max output.
+   */
+  private resolveDefaultMaxTokens;
+  /**
+   * Spread-friendly `system` fragment. Returns an empty object when no
+   * system prompt was hoisted out of the messages.
+   *
+   * When a per-call `cacheControl.breakpoints` hint is present (≥ 1),
+   * the system prompt is emitted as a single `TextBlockParam` carrying
+   * `cache_control: ephemeral` — the system prompt is the longest stable
+   * prefix on a turn, so one breakpoint there lets multi-turn agents
+   * read it back at the ~0.1x cache-read rate. Without the hint the
+   * system prompt stays a plain string (left uncached) so a one-shot
+   * call never pays the ~1.25x cache-write surcharge.
+   */
+  private buildSystem;
+  /**
+   * Let Anthropic select the last cacheable block when caching is enabled
+   * without a caller-selected breakpoint. An explicit breakpoint remains
+   * authoritative, so the request-level form is deliberately omitted then.
+   */
+  private buildAutomaticCacheControl;
+  /**
+   * Build a typed cache-control marker. The per-call
+   * `cacheControl.ttl` wins over the model's `promptCacheTtl`; with
+   * neither, TTL is omitted for Anthropic's 5-minute default.
+   */
+  private cacheControl;
+  /**
+   * Translate the neutral `reasoning` option into Anthropic's thinking
+   * settings, in the shape this model accepts (`thinkingMode`). Emitted
+   * only when the model declares the `reasoning` capability AND a
+   * reasoning option is supplied; otherwise returns an empty object.
+   *
+   * - Adaptive mode (Opus 4.7+, Sonnet 5+, Fable 5+, unknown ids):
+   *   `thinking: { type: "adaptive" }` (installed SDK
+   *   `ThinkingConfigAdaptive`, `messages.d.ts:1065`) plus
+   *   `output_config.effort` from the neutral effort, defaulting to
+   *   `"medium"`. `budget_tokens` is never sent — these models 400 on it
+   *   (claude-api ref). `reasoning.maxTokens` only sizes the default
+   *   `max_tokens` headroom.
+   * - Budget mode (Haiku 4.5, Opus/Sonnet 4.6, older):
+   *   `thinking: { type: "enabled", budget_tokens }`. An explicit
+   *   `reasoning.maxTokens` wins; otherwise the effort maps to a tiered
+   *   budget. `budget_tokens` must be ≥ 1024 (`ThinkingConfigEnabled`,
+   *   `messages.d.ts:1084`), so the budget is floored at that minimum.
+   *
+   * The neutral `effort: "none"` ("run without reasoning") is mapped per
+   * model by `noReasoningForm` (see `thinking-mode.ts` for the sources):
+   * - Claude Sonnet 5.5: `thinking: { type: "between_tools" }`, its only
+   *   thinking-off form. It is sent alone — no `output_config.effort` (the
+   *   model default, `high`, is within the `high`-or-below range it
+   *   requires) and no `display`, both of which the API rejects alongside it.
+   * - Claude Sonnet 5 and Claude Haiku 5.5: `thinking: { type: "disabled" }`
+   *   with no effort and no `display`. Haiku 5.5 accepts `disabled` only at
+   *   effort `high` or below; its default (`medium`) applies.
+   * - Claude Opus 5: adaptive thinking at `output_config.effort: "low"`.
+   *   Opus 5 accepts `disabled`, but with it the model can write a tool call
+   *   as plain text (the call never runs) and leak thinking tags; the lowest
+   *   effort is the documented alternative.
+   * - Opus 5.5 and Fable 5/5.1: no `thinking` field. These models have no
+   *   thinking-off form (`disabled` and `budget_tokens` are a 400 at every
+   *   effort), so thinking still runs at the model's default effort. Pass
+   *   `effort: "low"` to spend less.
+   * - Every other model: no `thinking` field, as before.
+   */
+  private buildThinking;
+  /**
+   * The thinking settings for `reasoning: { effort: "none" }`, per
+   * `noReasoningForm(this.name)` (documented on `buildThinking`).
+   */
+  private buildNoReasoning;
+  /**
+   * Spread-friendly tools fragment. Returns an empty object when no
+   * tools were supplied so the caller can unconditionally spread it.
+   *
+   * When `config.promptCaching` is on, marks the LAST tool with
+   * `cache_control: ephemeral` — Anthropic caches the whole prefix up
+   * to a breakpoint, and tools sit before `system` in that prefix, so
+   * one breakpoint on the final tool caches every tool definition.
+   * Reads bill at ~0.1x after the first write. The system prompt is
+   * deliberately left uncached: it carries per-turn placeholders, so a
+   * breakpoint there would pay the ~1.25x write surcharge every turn
+   * with no reads.
+   */
+  private buildTools;
+  /**
+   * Spread-friendly `output_config` fragment carrying both the native
+   * structured-output `format` and the adaptive-thinking `effort`, merged
+   * into one object (both live under `OutputConfig`, installed SDK
+   * `messages.d.ts:796-806`). Returns an empty object when neither applies,
+   * so budget-mode requests carry `output_config` only when a schema asks
+   * for it.
+   */
+  private buildOutputConfig;
+  /**
+   * Translate the neutral `responseSchema` option into Anthropic's
+   * native `output_config.format` (JSON-schema structured outputs).
+   *
+   * Only returned when the model declares the `structuredOutput`
+   * capability AND the schema is a proper root-object JSON Schema —
+   * Anthropic rejects non-object roots. When the capability is off
+   * (config override) or the schema is non-object, returns `undefined`:
+   * the agent has already injected a soft schema hint into the system
+   * prompt as the fallback, and client-side `validate()` still enforces
+   * shape.
+   */
+  private buildStructuredOutputFormat;
+  /**
+   * Concatenate every `text` content block into the single neutral
+   * `content` string. `tool_use` and other block types are ignored
+   * here — tool calls are surfaced separately via `extractToolCalls`.
+   */
+  private extractText;
+  /**
+   * Reshape Anthropic's `tool_use` content blocks into the neutral
+   * `ModelToolCallRequest[]`. Returns `undefined` when the model
+   * requested no tools so callers can branch on presence.
+   */
+  private extractToolCalls;
+  /**
+   * Preserve Anthropic's opaque extended-thinking blocks beside a tool
+   * request so the next assistant turn can replay their signatures exactly.
+   */
+  private buildThinkingMetadata;
+  /**
+   * Normalize Anthropic's `usage` block into the neutral `Usage` shape.
+   * Anthropic reports `input_tokens` / `output_tokens` separately with
+   * no pre-summed total, so `total` is computed. `input_tokens` is the
+   * uncached remainder only — cache reads (`cachedTokens`) and writes
+   * (`cacheWriteTokens`, with the 1-hour share in `cacheWrite1hTokens`)
+   * come on top of it — so the usage is marked
+   * `inputIncludesCache: false`. Anthropic also reports
+   * `output_tokens_details.thinking_tokens` as the reasoning subset of
+   * its inclusive `output_tokens`; it is surfaced as `reasoningTokens`
+   * when present, without changing the billing total. Server-side
+   * compaction iterations are added in (see {@link compactionIterationUsage}).
+   * `cost` is attached when the model is priced.
+   */
+  private extractUsage;
+  /**
+   * Wrap a thrown provider error into the typed `AIError` hierarchy and
+   * emit the standard error log line before it propagates. Shared by
+   * every catch site so the log shape stays identical.
+   */
+  private logAndWrap;
+}
+//#endregion
+export { AnthropicModel };
+//# sourceMappingURL=model.d.mts.map

package/esm/model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.mts","names":[],"sources":["../../../../../../../packages/ai-anthropic/src/model.ts"],"mappings":";;;;;;;;AAmNA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,cAAA,YAA0B,aAAA;EAAA,SACrB,IAAA;EAAA,SACA,QAAA;EAAA,SACA,YAAA,EAAc,iBAAA;EAAA,SACd,OAAA,GAAU,YAAA;EAAA,iBAET,MAAA;EAAA,iBACA,MAAA;EAAA,iBACA,YAAA;EARoB;EAAA,iBAUpB,eAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,MAAA;cAGf,MAAA,EAAQ,SAAA,EACR,MAAA,EAAQ,oBAAA,EACR,QAAA;EAbc;;;;;;EA6DH,QAAA,CAAS,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,aAAA;EArD/D;EA4DV,YAAA,CACL,QAAA,EAAU,OAAA,IACV,OAAA,EAAS,gBAAA;IAAqB,MAAA;EAAA,IAC7B,yBAAA;EACI,YAAA,CACL,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,gBAAA;IAAqB,MAAA;EAAA,IAC9B,4BAAA;EACI,YAAA,CACL,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,gBAAA;IAAqB,MAAA;EAAA,IAC9B,gBAAA;EAlBkD;;;;;;;EAAA,QAqC7C,kBAAA;EA5BwB;EA2DzB,IAAA,CACL,OAAA,EAAS,4BAAA,EACT,OAAA,GAAU,uBAAA,GACT,OAAA,CAAQ,aAAA;EACJ,IAAA,CACL,OAAA,EAAS,yBAAA,EACT,OAAA,GAAU,uBAAA,GACT,aAAA,CAAc,gBAAA;EACV,IAAA,CACL,OAAA,EAAS,gBAAA,EACT,OAAA,GAAU,uBAAA,GACT,OAAA,CAAQ,aAAA,IAAiB,aAAA,CAAc,gBAAA;EAAA,QAqB5B,eAAA;EAxFZ;;;;;;;;;;;EAkIW,WAAA,CAAY,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA;EAzGnE;;;;;;;;;;;;EAkJM,MAAA,CACZ,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,gBAAA,GACT,aAAA,CAAc,gBAAA;EAAA,QAOF,aAAA;EAtHE;;;;;;EAAA,QA4TT,kBAAA;EAxTG;EAAA,QA4WH,oBAAA;EA5WkC;;;;;;EAAA,QA8XlC,QAAA;EA/TmE;;;;;;;;;EAAA,QA+VnE,SAAA;EAlDA;;;;;;;;EAAA,QAiIA,iBAAA;EA+MA;;;;;;;;;;;AAgQU;EAhQV,QAzKA,WAAA;;;;;;;;;;;;;;UA2DA,uBAAA;;;;;;;;;;;;;UAsBA,WAAA;;;;;;UA0BA,0BAAA;;;;;;UAeA,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA+CA,aAAA;;;;;UAwCA,gBAAA;;;;;;;;;;;;;;UA8BA,UAAA;;;;;;;;;UAyCA,iBAAA;;;;;;;;;;;;;UA8BA,2BAAA;;;;;;UAmBA,WAAA;;;;;;UAYA,gBAAA;;;;;UAuBA,qBAAA;;;;;;;;;;;;;;;UA6BA,YAAA;;;;;;UAgCA,UAAA;AAAA"}