@combycode/llm-sdk 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,107 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-07-11
+
+### Added
+- **Typed structured-output failure + opt-in repair.** Structured output that can't be parsed now throws
+  a typed `InvalidFinalOutputError` (extends `AgentRunError`, carries `reason: 'invalid_final_output'` and
+  the model's `rawText`) instead of a bare `SyntaxError`, so callers can `instanceof`/inspect/retry.
+  `structuredComplete` gains an opt-in `structured.repairAttempts` (default 0): on a parse failure it
+  re-prompts with the error up to N times before throwing. Exports `AgentRunError`,
+  `InvalidFinalOutputError`. (`max_steps` / `model_refusal` stay returned results, differentiated by
+  `finishReason` / `AgentRunReport.reason`; run-error handler hooks can layer on later.)
+- **`user_profile_id` + Interactions `cached_content`.** Anthropic forwards `providerOptions.userProfileId`
+  to the `anthropic-user-profile-id` header; Google Interactions maps `providerOptions.cachedContent` to
+  its `cached_content` resource.
+- **Sampling penalties.** `presencePenalty` / `frequencyPenalty` ([-2, 2]) on `complete()` / `stream()`
+  (and `NormalizedRequest`), mapped to the providers that accept them — OpenAI/xAI **chat-completions**
+  (`presence_penalty` / `frequency_penalty`), OpenRouter (inherited), Google **generateContent**
+  (`generationConfig.presencePenalty` / `frequencyPenalty`) and **Interactions** (snake_case). Ignored by
+  OpenAI/xAI **Responses** and Anthropic, which don't accept them (verified against the SDK sources — the
+  Responses API has no penalty fields). Verified live on OpenAI, Google, and xAI.
+- **Unified `web_fetch` hosted tool.** New `{ type: 'web_fetch' }` builtin that reads a
+  user-provided URL, mapped to Anthropic's `web_fetch_20260318` (GA; `params` like `allowed_domains`
+  / `blocked_domains` / `citations` / `max_content_tokens` / `max_uses` forwarded verbatim, with
+  `allowed_callers: ['direct']` defaulted so it works on chat models) and Google's `urlContext` tool.
+  The fetched URL surfaces on `response.builtinToolCalls` (`{ tool: 'web_fetch', url }`) and the
+  streamed `builtin_tool_start` / `builtin_tool_end` events, normalized across both providers.
+  `capabilities.builtinTools` / `catalog.supportsBuiltinTool()` / `select('web_fetch')` report it on
+  Anthropic + Google (OpenAI's `web_search` already opens pages; xAI / OpenRouter expose no fetch
+  tool). Verified live on Anthropic and Google.
+- **Builtin-tool call payloads.** `BuiltinToolCall` (and the `builtin_tool_end` stream event) now
+  carry what the tool ran: `code` + `output` (stdout) for `code_interpreter`, and `query` (search
+  step) or `url` (page-open step) for `web_search` — normalized across every provider (OpenAI/xAI
+  `code_interpreter_call.code` + `web_search_call.action` `query`/`queries[]`/`url`, Anthropic
+  `server_tool_use.input` streamed via `input_json_delta` and correlated to its `*_tool_result`
+  stdout, Google `executableCode`/`codeExecutionResult` + grounding `webSearchQueries`). A single
+  OpenAI web search is a multi-step agent: `search` actions carry a query, `open_page`/`find`
+  actions carry the URL they read. Available on both `complete()` and streamed responses; verified
+  live on all four providers.
+
+### Changed
+- **Anthropic web-search bumped to `web_search_20260318`** (from `web_search_20250305`) and now forwards
+  the unified `BuiltinTool.params` verbatim — `allowed_domains`, `blocked_domains`, `user_location`,
+  `response_inclusion`, `max_uses` (previously all silently dropped). The new version defaults to
+  *programmatic* tool calling (via code execution), which chat models like haiku reject, so the adapter
+  sends `allowed_callers: ['direct']` by default to preserve the classic direct-call behaviour; callers
+  override any default through `params`. Live-verified across all providers (scenario 27, 5/5).
+
+### Fixed
+- **xAI `service_tier` maps to xAI's own enum.** The xAI adapter inherited OpenAI's tier map and could
+  emit `auto` / `flex` / `scale`, which xAI's API rejects (its `ServiceTier` is `default` | `priority`
+  only). It now remaps from the unified tier — `standard` → `default`, `priority` → `priority`, and any
+  value xAI can't honor is omitted (the server picks its default) rather than 400'ing. Live-verified:
+  `priority` sent and billed back (`usage.serviceTier`/`pricingTier`), `flex` no longer errors.
+- **Agent loop no longer swallows failed runs into empty text.** `AgentLoop.complete()` and
+  `.stream()` caught any mid-run LLM error, set `finishReason:'error'`, and returned an empty
+  `CompletionResponse` (or ended the stream) with the error message dropped — so a tool-using
+  `complete()` / `delegate()` / `handoff()` returned `""` on an auth failure, rate limit, context
+  overflow, etc., while the same call *without* tools threw. Both now **re-throw** the original error
+  (preserving `LLMError` kind/status) after finalizing metrics/hooks, matching the no-tools path and
+  the raw client stream. `AgentLoop.run()` is unchanged — it still returns an `AgentRunReport` with
+  `reason:'error'` + `error` for callers that want partial results. Live-verified (bad key → thrown
+  `auth` error, not empty text).
+- **Agent loop now continues stateful turns server-side.** After a tool call the loop stamped its
+  assistant turn without provenance, so multi-turn runs on a stateful API always resent the full
+  transcript. On Google Interactions that transcript replay is *rejected* (the API requires resuming
+  by `previous_interaction_id`), which surfaced as an **empty final answer** on agentic tool use. The
+  loop now stamps `id` / `createdAt` / `origin.serverStateId` (via the shared `buildAssistantMessage`),
+  so the server-state brain continues by id and sends only the new turn — gated, as before, by catalog
+  support, the retention TTL (openai/xai 30d, google 72h), and model binding. Live-verified: Interactions
+  agentic round-trip now answers; OpenAI Responses / Anthropic tool loops unchanged.
+- **Google Interactions streaming (opt-in `api: 'interactions'`) brought current with the 2.10 wire.**
+  The regenerated Interactions client replaced the old `content.delta` / `interaction.complete` events
+  with a step machine — `step.start` / `step.delta` / `step.stop`, `interaction.created` /
+  `interaction.completed` / `interaction.status_update` — so the previous parser produced no output.
+  The parser now reads `step.delta` payloads (`text`, `thought_summary` → thinking, `arguments_delta`),
+  opens/attaches/closes a function call across `step.start` → `arguments_delta` → `step.stop` (the
+  `arguments_delta` carries no id, so a per-stream parser correlates it), and finishes on
+  `interaction.completed` / `interaction.failed` with usage from `interaction.usage`. Live-verified
+  against the 2.10 API (streamed text, tool calls, usage). The default Google path (`generateContent`)
+  is unaffected.
+- **OpenAI web-search query precedence.** OpenAI deprecated the singular `web_search_call.action.query`
+  in favour of `action.queries[]`; the Responses adapter now prefers the array and falls back to the
+  scalar, so `BuiltinToolCall.query` stays populated on the new wire.
+- **Duplicate OpenAI code-execution files.** When code calls `plt.show()` *and* saves the figure,
+  OpenAI emits an extra auto-display container file alongside the saved one — surfacing the same
+  chart twice on `response.files`. The Responses adapter now drops the auto-display artifact (an
+  image citation named after its own file id, with a zero-width span) when the same image was also
+  saved, matching ChatGPT's own UI. A display-only run keeps its sole figure; distinct saved files
+  are never collapsed. Investigated across providers: only OpenAI has this pattern (Anthropic/xAI
+  return only saved files; Google returns one artifact per output) — so the fix is scoped to the
+  OpenAI Responses adapter.
+
+## [1.5.1] - 2026-07-06
+
+### Changed
+- `retrieveFile` / `streamFile` now send Anthropic's `anthropic-dangerous-direct-browser-access:
+  true` header in the browser, for consistency with the completion adapter. **Note:** this does
+  NOT make Anthropic hosted-tool files downloadable from a browser — Anthropic's Files API
+  (`GET /v1/files/{id}/content`) does not return CORS headers (unlike `/v1/messages`), so file
+  retrieval for Anthropic is **server-side only** (verified against the API + the official docs).
+  OpenAI works in-browser; Google and xAI return files inline (no fetch), so they work too.
+
 ## [1.5.0] - 2026-07-06
 
 ### Added
@@ -137,6 +238,7 @@ First public release.
 - Service tiers end to end (request → bill → cost).
 - Cross-environment: runs on Node, Bun, and the browser. ESM, zero runtime deps.
 
+[1.6.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.6.0
 [1.2.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.2.0
 [1.1.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.1.0
 [1.0.0]: https://github.com/combycode/llm-sdk-ts/releases/tag/v1.0.0