Changelog

@ratel-ai/sdk release history · npm · source

Synced verbatim from the package's CHANGELOG.md at ratel-ai/ratel@3be0ecb — do not edit by hand. Regenerate with pnpm sync:api in apps/docs.

All notable changes to @ratel-ai/sdk are documented here.

The format follows Keep a Changelog and this package adheres to Semantic Versioning.

[0.4.1] - 2026-07-10

Added

• configureTelemetry opts into message/tool content capture programmatically: captureContent sets the exact ContentCapture mode (validated like the env var — case-insensitive, legacy boolean forms accepted — throwing a TypeError on garbage before any exporter is wired), and includeSpanAndEvents is boolean sugar (true → SPAN_AND_EVENT, false → NO_CONTENT). captureContent wins over includeSpanAndEvents; when neither is provided, OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT keeps ruling (a provided option beats the env var, as in OTel code-over-env precedence). The handle's shutdown() restores env-driven behavior via a generation-scoped clear (clearContentCapture), so a stale handle shutting down late never clobbers an override a newer configureTelemetry installed. ContentCapture, setContentCapture, and clearContentCapture are re-exported from @ratel-ai/sdk (new ConfigureTelemetryOptions type).

[0.4.0] - 2026-07-07

Added

• OpenTelemetry emission. The SDK now opens an OTel span at each funnel boundary — execute_tool (gen_ai.operation.name, gen_ai.tool.name, ratel.tool.args_size_bytes, plus ratel.upstream.server for MCP-proxied tools), ratel.search (target, top_k, origin, hit_count), ratel.skill.load, ratel.upstream.register, and ratel.auth.flow — alongside the existing local recordEvent stream, which is unchanged. Emission is transparent and free by default: spans flow to whatever OpenTelemetry provider is registered and are a no-op until one is, so a host already running OTel sees Ratel's funnel on its traces with no setup. Built on @opentelemetry/api + the OTel-free @ratel-ai/telemetry vocabulary, so the base install stays OTel-SDK-free.
• configureTelemetry({ apiKey }) convenience wiring (with TelemetryHandle / InitOptions): lazily loads the optional @ratel-ai/telemetry-otlp peer to ship the SDK's spans to Ratel Cloud (or any OTLP endpoint). Hosts already running OpenTelemetry skip it and add ratelSpanProcessor from @ratel-ai/telemetry-otlp instead.
• Message/tool content (ratel.search.query, gen_ai.tool.call.arguments / .result) rides span attributes only when OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT selects a span mode (SPAN_ONLY / SPAN_AND_EVENT); default off. ratel.tool.args_size_bytes is measured in UTF-8 bytes.

[0.3.0] - 2026-07-06

Added

• ToolCatalog / SkillCatalog accept a default method ("bm25" | "semantic" | "hybrid") and search(query, topK, origin?, method?) takes a per-call override. "bm25" (default) is unchanged and model-free; "semantic" / "hybrid" load a local embedding model and throw if it fails to load. Exposed via the native searchWithMethod binding and the SearchMethod type.
• A "semantic"/"hybrid" catalog embeds each tool/skill eagerly at register (incrementally), so searches never pay the corpus-embedding cost. New catalog.buildEmbeddings() pre-computes embeddings on demand (e.g. after a bulk register). BM25 catalogs do neither. A semantic/hybrid search on a catalog with no embeddings built throws (embeddings not computed) rather than embedding during the search.

[0.2.1-rc.1] - 2026-07-04

Changed

• First release cut under the per-package release scheme (ADR-0008): @ratel-ai/sdk (loader + platform packages) now versions and ships independently, tagged sdk-js-v*. No API changes since 0.2.0.

[0.2.0] - 2026-06-16

Changed

• BREAKING: the discovery gateway tool is renamed search_tools → search_capabilities. It now returns two independently-ranked, separately-budgeted buckets — { tools, skills } — so a relevant skill is never crowded out by matching tools. New surface: searchCapabilitiesTool/SEARCH_CAPABILITIES_ID. The old searchToolsTool/SEARCH_TOOLS_ID are kept as deprecated aliases (see Deprecated), so 0.1.x code keeps working after upgrading.

Added

• First-class skills: SkillCatalog, getSkillContentTool (get_skill_content), and Skill/SkillHit/SkillRegistry. Skills are reusable playbooks ranked by a separate BM25 corpus and loaded on demand.
• Skill–tool coupling: a Skill can declare a tools list, and search_capabilities pulls a matched skill's declared tools into the tools bucket — additively (beyond topKTools) and deduped against query hits — so the agent gets the playbook and the tools it needs in one turn.

Deprecated

• searchToolsTool, SEARCH_TOOLS_ID, and the SearchToolHit/SearchToolsGroup/SearchToolsResult/SearchToolsToolOptions types. They retain their pre-0.2.0 behaviour — a tools-only { groups } result and the search_tools id — so upgrading from 0.1.x does not break existing callers. Migrate to searchCapabilitiesTool; the aliases will be removed in a future release.

Fixed

• Gateway error payloads (invoke_tool, get_skill_content) carry isError: true, so a host can flag a failed call rather than read it as content.
• invoke_tool rejects a non-object args instead of forwarding stray top-level keys.
• search_capabilities validates topKTools/topKSkills (declared integer, positive): 0, negative, and fractional values fall back to the default instead of returning zero results — or, via a negative wrapping to u32 in the native layer, an unbounded set. TypeScript and Python behave identically.
• search_capabilities advertises the skills bucket and get_skill_content in its description only when a non-empty skill catalog is wired in.
• Skill.tags and Skill.body are optional (default []/""), matching the Python SDK — a minimal { id, name, description } skill is valid.

[0.1.6] - 2026-06-10

Fixed

• TypeScript typehint for JSON-schema tool input/output (#54).

[0.1.5] - 2026-05-10

Added

• Initial release on the v1 (revamp) line. TypeScript SDK over the Rust core: BM25 tool retrieval, MCP ingestion, framework-neutral gateway tools. See the package README for the full surface.
• ToolCatalog accepts { trace } config in its constructor — noop (default), memory, or jsonl. Captured events flow through the Rust core sink (ADR-0007). New recordEvent, drainTraceEvents, and an optional third origin argument on search.
• searchToolsTool emits gateway_search with origin: "agent". invokeToolTool emits gateway_invoke on success and gateway_error for unknown ids, needs_auth, and underlying throws.
• ToolCatalog.invoke emits invoke_start / invoke_end / invoke_error around the executor with args_size_bytes and took_ms.
• registerMcpServer emits upstream_register on connect and upstream_invoke / upstream_error per upstream call. New searchWithOrigin and trace plumbing on the underlying NAPI ToolRegistry. SearchOrigin is now "direct" | "agent" (was "user" | "agent"); the union is exported from the package entry point.

Changed

• Rewrote search_tools description to nudge agents toward discovery before falling back to broad listing.