@fllf/agent-sdk 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,169 @@
+# Changelog
+
+All notable changes to this package should be recorded here.
+
+This project follows semver. While the package is below `1.0.0`, stable
+integration APIs should remain compatible whenever practical. Experimental and
+low-level extension points may change in minor versions when the change is
+documented here.
+
+## Unreleased
+
+## 0.1.3 - 2026-07-05
+
+### Breaking changes
+
+- `Message.content` / `ChatMessage.content` widened from `string` to
+  `MessageContent` (`string | ContentBlock[]`, text/image blocks). Plain string
+  content keeps working; code that assumed `content` is always a string should
+  use `Message.text` or `contentToText()`.
+- `ToolExecutor.execute()` now returns a structured `ToolCallOutcome`
+  (`{ toolCallId, toolName, content, isError }`) instead of a plain string.
+- `ChatStreamChunk.toolCallDelta: unknown` replaced with typed
+  `toolCallDeltas: ToolCallDelta[]`; chunks can now carry `finishReason` and
+  final `usage`.
+- `ToolCallingExecutor` defaults to `onMaxIterations: 'finalize'`: when the
+  iteration budget runs out it issues one final no-tools request instead of
+  throwing. Pass `{ onMaxIterations: 'throw' }` for the previous behavior; in
+  both modes the executed trajectory is persisted to history.
+- `Config.temperature` no longer defaults to `0.7`. When unset, no temperature
+  is sent and the provider/model default applies.
+- Default tool result serialization now uses `JSON.stringify` for non-string
+  results instead of `String(result)`.
+- The official `openai` provider sends `max_completion_tokens` instead of the
+  deprecated `max_tokens` (other OpenAI-compatible providers keep
+  `max_tokens`), and streaming requests set
+  `stream_options: { include_usage: true }`.
+- RAG: `RagSearchTool` no longer exposes `tenantId` / `knowledgeBaseId` / `acl`
+  as model-fillable parameters; they must come from server-side
+  `defaultRetrieveOptions`. RAG document ids no longer include the content
+  checksum, and `answer()` no longer forwards retrieval `minScore` to the
+  context builder (use the new `minFusedScore`).
+
+### Added
+
+- Anthropic provider (`provider: 'anthropic'`, env: `ANTHROPIC_API_KEY` /
+  `ANTHROPIC_MODEL` / `ANTHROPIC_BASE_URL`, default model `claude-opus-4-8`):
+  Messages API mapping incl. multimodal content, tool_use/tool_result with
+  `is_error`, streaming SSE → typed chunks, structured output via
+  `output_config.format`, prompt-cache usage fields. `autoDetect` falls back
+  to Anthropic when only `ANTHROPIC_API_KEY` is set.
+- Provider-neutral tool schema: `ToolDefinition` replaces the OpenAI-shaped
+  `ChatToolSchema` in `ChatRequest.tools` (`Tool.toToolSchema()` /
+  `ToolRegistry.toToolSchemas()`; the OpenAI-shaped methods remain as
+  deprecated wrappers). `toolChoice` supports forcing a specific tool
+  (`{ type: 'tool', name }`); `ChatRequest.reasoning.effort` maps to
+  Anthropic `output_config.effort` / OpenAI `reasoning_effort`;
+  `ChatMessage.cacheControl: 'ephemeral'` marks prompt-cache breakpoints;
+  responses and stream chunks expose `reasoning` / `reasoningDelta` and
+  `cacheCreationPromptTokens`.
+- Optimistic concurrency for message history: `getVersion()` +
+  `addMany(messages, { expectedVersion })` with
+  `HistoryVersionConflictError` (CAS retry pattern for multi-instance
+  deployments), plus a reference `PostgresMessageHistoryStore` working with
+  any `query()` client, including schema SQL and windowed reads.
+- Multimodal message content: `ContentBlock` (`textBlock()`, `imageUrlBlock()`,
+  `imageBase64Block()`), `contentToText()`, and user-message image mapping in
+  OpenAI-compatible providers. `Agent.run()` / `Agent.stream()` accept
+  `MessageContent` input.
+- Streaming tool calling: `ToolCallingExecutor` implements
+  `StreamingAgentExecutor`, emitting `agent:text_delta`, typed
+  `agent:tool_call` / `agent:tool_result` events, and falling back to
+  non-streaming models transparently. `ChatStreamAccumulator` aggregates
+  chunks into a full `ChatResponse`.
+- Parallel tool execution: multiple tool calls in one model turn run
+  concurrently via `ToolExecutor.executeMany()`, with result order preserved.
+- Context window management: `Config.maxInputTokens` (env: `MAX_INPUT_TOKENS`)
+  enables token-aware history truncation with a pluggable `TokenEstimator`;
+  `truncateToTokenBudget()` and `repairLeadingToolContext()` are exported.
+  `MessageHistory.get({ limit })` now repairs orphan tool messages the same
+  way `addMany()` overflow does.
+- Reliability: transport errors without an HTTP status (`ECONNRESET`,
+  `fetch failed`, undici timeouts, …) normalize as retryable provider errors;
+  `llm:retry` observability events expose retry attempts.
+- Cost observability: `llm:end` and `agent:end` events carry token `usage`
+  (including `cachedPromptTokens` when reported); `ChatResponse` and stream
+  chunks expose `finishReason`.
+- Tool errors returned to the model are flagged with `isError` on the tool
+  message metadata, and unknown-tool feedback lists the registered tools.
+- RAG: `replaceExisting` re-ingestion now cleans up prior versions by stable
+  document id and skips unchanged documents (`skippedDocumentIds`); pgvector
+  search restores HNSW-index-friendly `ORDER BY`; Postgres stores upsert in
+  multi-row batches (≤500 rows).
+
+### Added (previous)
+
+- Documented stable integration APIs, lower-level extension points, API
+  compatibility expectations, and the release checklist.
+- Added `npm run pack:dry-run` for pre-publish package inspection.
+- Added stable SDK error classes for Agent, Tool, History, and Config layers,
+  including code/retryability metadata.
+- Added Tool runtime controls for execution context, timeout, abort propagation,
+  error mode, and result serialization.
+- Added observability event levels, optional span fields, observer redaction
+  hooks, and `CollectingObserver`.
+- Added `MessageJSON`, `Message.fromJSON()`, and `reviveMessage()` as the
+  documented message persistence contract.
+- Added custom provider, history store, executor, observer, and production
+  factory examples.
+- Added `ModelProviderRegistry` and `LLM` provider registry injection for scoped
+  provider registration.
+- Added shared `buildChatMessages()` and `buildChatRequest()` helpers for custom
+  executor implementations.
+- Added `MessageHistory.get({ limit, before })` window reads and the
+  `applyMessageHistoryWindow()` helper.
+- Added `BaseExecutor` and type-level streaming executor contracts through
+  `StreamingAgentExecutor` and `AgentStreamEvent`.
+- Added downstream testing helpers: `ScriptedChatModel`, `FakeChatModel`,
+  `FakeTool`, `createTestAgent()`, and
+  `assertMessageHistoryStoreContract()`.
+- Added tool schema snapshot helpers for downstream tests.
+- Added Tool permission policies through `canExecute()` and
+  `ToolPermissionError`.
+- Added `Agent` run option validation and injectable `runIdFactory`.
+- Added runtime provider capability checks for tool calling, structured output,
+  and streaming through `LLMUnsupportedCapabilityError`.
+- Added `Config.fromEnv()` diagnostics through `envWarnings`, `onWarning`, and
+  strict `ConfigError` rejection.
+- Added stable package subpath exports for agent, config, executors, history,
+  llm, messages, observability, rag, testing, and tools modules.
+- Added a stable `errors` subpath export for typed SDK error handling.
+- Added `AgentLifecycleHooks` for `beforeRun`, `afterRun`, and `onRunError`
+  integration around `Agent.run()`.
+- Added constructor validation for `Config` and `LLM` runtime options.
+- Added `npm run test:exports` to verify root and subpath package exports after
+  build.
+- Added simple-chat `Agent.stream()` runtime support through
+  `StreamingAgentExecutor`, with default support in `SimpleChatExecutor`.
+- Added `ToolConfigurationError` and constructor-time validation for tool
+  names, descriptions, schemas, timeout, error mode, permission checker, and
+  result serializer.
+- Added offline `streaming-chat` and `tool-error-policy` examples.
+- Added explicit `ToolRegistry` duplicate-name handling with fail-fast defaults
+  and opt-in replacement for compatibility adapters.
+- Added RAG chunking improvements for Chinese and mixed-language boundary
+  handling, including stable overlap behavior when text has no whitespace.
+- Added shared sparse keyword tokenization for in-memory and Postgres keyword
+  stores, including technical identifier splitting, Chinese n-grams, and
+  `title` / `headingPath` indexing.
+- Added `ParentChildExpandingRetriever` for expanding child chunk hits into
+  parent or neighboring context chunks.
+- Added `QaPairChunker` for FAQ-style question/answer documents.
+- Added experimental `SemanticChunker` for optional embedding-based semantic
+  chunking.
+
+### Changed
+
+- Replaced non-RAG source-level bare runtime `Error` throws with typed SDK/LLM
+  errors where they are part of public execution flow.
+- Sparse RAG keyword indexes now use expanded token terms. Existing persistent
+  keyword indexes should be rebuilt or documents should be re-ingested after
+  upgrading.
+
+### Compatibility notes
+
+- Breaking changes must include migration notes in this file before release.
+- Experimental API changes should name the affected exports and expected
+  replacement path.
+- `SemanticChunker` is experimental and must be selected explicitly; it is not
+  used by `AutoChunker` by default.