@ratel-ai/sdk

v0.7.0 · TypeScript · npm · source

Generated from the doc comments at ratel-ai/ratel@d8635d5 — do not edit by hand. Regenerate with pnpm sync:api in apps/docs.

@ratel-ai/sdk — TypeScript SDK for Ratel, the context engineering platform for AI agents. In-process, no infra: a native (Rust) BM25/semantic/hybrid index behind ToolCatalog and SkillCatalog, MCP ingestion via registerMcpServer, and the framework-neutral capability tools (searchCapabilitiesTool, invokeToolTool, getSkillContentTool) that let a model discover and run what the catalogs hold. Everything emits OTel ratel.*/gen_ai.* spans plus a local trace stream (ADR-0007).

Classes

DimensionMismatchError

A vector's dimension did not match the embedding cache's — the model changed under an existing corpus. A subclass of EmbedderError (so instanceof EmbedderError still catches it), mirroring Python's DimensionMismatchError. Its EmbedderError.code is "DimensionMismatch".

Extends

• EmbedderError

Constructors

Constructor

new DimensionMismatchError(message): DimensionMismatchError

Parameters

Returns

DimensionMismatchError

Overrides

EmbedderError.constructor

Properties

cause?

optional cause?: unknown

Inherited from

EmbedderError.cause

code

readonly code: string

Stable machine-readable discriminant — one of "Load", "Download", "NotCached", "ModelMismatch", "DimensionMismatch", "EmbeddingsNotBuilt", "Inference", or "CacheUnwritable". Prefer this (or instanceof) over parsing Error.message.

Inherited from

EmbedderError.code

message

message: string

Inherited from

EmbedderError.message

name

name: string

Inherited from

EmbedderError.name

stack?

optional stack?: string

Inherited from

EmbedderError.stack

stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

EmbedderError.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Returns

void

Inherited from

EmbedderError.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

EmbedderError.prepareStackTrace

EmbedderError

An embedding model failed to load, download, or run — the base class for every dense-retrieval failure raised from register / searchAsync on a "semantic"/"hybrid" catalog. Mirrors Python's EmbedderError.

Extends

• Error

Extended by

• DimensionMismatchError

Constructors

Constructor

new EmbedderError(message, code): EmbedderError

Parameters

Returns

EmbedderError

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown

Inherited from

Error.cause

code

readonly code: string

Stable machine-readable discriminant — one of "Load", "Download", "NotCached", "ModelMismatch", "DimensionMismatch", "EmbeddingsNotBuilt", "Inference", or "CacheUnwritable". Prefer this (or instanceof) over parsing Error.message.

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

IntentGraph

A shared usage-ranking intent graph (ADR-0014): clusters of past queries, each remembering the capabilities invoked after them.

Hand the same instance to both registries. One cluster carries a tools map and a skills map, so a tool catalog and a skill catalog sharing a graph learn from and rank against one set of clusters. Giving them separate graphs duplicates every cluster and halves the evidence behind each.

Constructors

Constructor

new IntentGraph(): IntentGraph

An empty graph — knows nothing until a search is followed by an invoke.

Returns

IntentGraph

Accessors

clusterCount

Get Signature

get clusterCount(): number

How many clusters the graph holds. 0 is the cold-start state, in which the graph contributes nothing to ranking.

Returns

number

rev

Get Signature

get rev(): number

Monotonic write counter — bumped once per mutation (a confirmed observation, a rebuild). Never affects ranking; it is a primitive for your storage layer. Snapshot it after each save: a later value means unsaved learning (save-when-changed), and a stored graph whose rev is higher than the one you loaded was written by another process (stale-base detection).

Returns

number

Methods

toJson()

toJson(): string

Serialize to the protocol/v1 wire form — for inspection, or to carry what was learned across processes.

The graph is in-process only; persistence is yours. It mutates on every confirmed invoke, so unsaved observations are lost on a crash — persist on a cadence or at shutdown. Use rev to save only when it changed and to detect a concurrent writer; single-writer is the supported model.

SENSITIVE: the output contains the raw text of past user queries (the cluster members). Treat a persisted graph like your query/telemetry log — restrict permissions (0600), keep it out of version control and images, and do not ship it to a less-trusted store.

Returns

string

fromJson()

static fromJson(json): IntentGraph

Adopt a graph serialized in the protocol/v1 wire form — produced by a previous toJson or by Ratel Cloud.

Throws if the JSON is malformed or declares a schema version this build does not read (a consumer rejects rather than degrading).

Parameters

Returns

IntentGraph

McpToolsListError

Paginated MCP tools/list failed — repeated cursor or page cap exceeded. Thrown by registerMcpServer when listing upstream tools; mirrors Python's McpToolsListError.

Extends

• Error

Constructors

Constructor

new McpToolsListError(message, code): McpToolsListError

Parameters

Returns

McpToolsListError

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown

Inherited from

Error.cause

code

readonly code: McpToolsListErrorCode

Prefer McpToolsListErrorCode (or instanceof) over parsing Error.message.

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

SkillCatalog

In-memory catalog of skills, ranked by the native SkillRegistry retrieval engine. The on-demand analog of ToolCatalog: registered skills are searched by relevance; the matching body is fetched only on SkillCatalog.invoke.

Constructors

Constructor

new SkillCatalog(options?): SkillCatalog

Create an empty catalog.

Parameters

Returns

SkillCatalog

Accessors

experimentalAdaptiveRankingStatus

Get Signature

get experimentalAdaptiveRankingStatus(): AdaptiveRankingStatus

Whether adaptive usage ranking is active, inactive, or paused by a model change — see the native AdaptiveRankingStatus.

Returns

AdaptiveRankingStatus

Methods

drainTraceEvents()

drainTraceEvents(): unknown[]

Drain the envelopes captured by a "memory" trace sink, emptying its buffer. Same contract as ToolCatalog.drainTraceEvents.

Returns

unknown[]

The captured envelopes in record order; [] unless the active sink is "memory".

experimentalDisableAdaptiveRanking()

experimentalDisableAdaptiveRanking(): void

Turn adaptive usage ranking off; the graph keeps what it learned.

Returns

void

experimentalEnableAdaptiveRanking()

experimentalEnableAdaptiveRanking(graph, options?): void

Turn on adaptive usage ranking against graph (ADR-0014): the catalog ranks against what users have actually invoked after similar queries, and keeps learning as it is used.

Pass the same IntentGraph to a ToolCatalog so both learn into one set of clusters.

Set rebuildOnModelChange to auto-recover a model-mismatched graph on the next dense (semantic/hybrid) search rather than staying paused until you call experimentalRebuildIntentGraph yourself. Off by default — the rebuild is an embedding pass (cost, possible EmbedderError, and it mutates the graph).

Parameters

Returns

void

experimentalRebuildIntentGraph()

experimentalRebuildIntentGraph(): Promise<void>

Re-embed the intent graph's members under the current model and replace its centroids — call after changing the embedding model. Preserves members, support, and edges. See experimentalEnableAdaptiveRanking.

Returns

Promise<void>

get()

get(skillId): Skill | undefined

Look up a skill by id.

Parameters

Returns

Skill | undefined

The skill as registered (including body), or undefined for an unknown id.

has()

has(skillId): boolean

Whether a skill with this id is registered.

Parameters

Returns

boolean

true if SkillCatalog.invoke would find it.

invoke()

invoke(skillId): string

Return a skill's body for dispatch, recording a skill_invoke event. Throws on an unknown id — callers at the capability-tool boundary translate that into a structured error for the agent.

Parameters

Returns

string

The skill's body ("" when it was registered without one).

recordEvent()

recordEvent(event): void

Record a custom event on the local trace stream (ADR-0007). Same contract as ToolCatalog.recordEvent: the event is a tagged wire-shape object ({ type: "...", ... }, snake_case fields) and an unknown shape throws.

Parameters

Returns

void

register()

register(skills): Promise<void>

Add one skill or a batch to the catalog — the single entry point for both. Replaces an id in place when already registered. Name, description, and tags are indexed for ranking; tools, metadata, and body are stored but not indexed (body is the dispatch payload, fetched by SkillCatalog.invoke). On a "semantic"/"hybrid" catalog, embeds the batch in one pass on a libuv worker after metadata is indexed — embedding errors surface here, at registration. A "bm25" catalog never loads a model.

A model or dimension change is not recovered in place — construct a new catalog and re-register.

Parameters

Returns

Promise<void>

replaceAll()

replaceAll(skills): PendingReplace

Make skills the entire content of the catalog: ids absent from the batch are removed, the rest are added or updated. The whole-catalog counterpart to SkillCatalog.register, for a source that reloads a catalog rather than pushing individual changes. Mutates in place, so every holder of this catalog — ratel()'s r.skills, each adapted view, and the capability tools taken from modelTools() — observes the reload without being rebuilt.

Removal is unconditional. Skills registered in-process are dropped just like any others, since the batch is the catalog. A host that keeps local skills alongside a remote source composes the batch itself: await catalog.replaceAll([...localSkills, ...remoteSkills]).

Embedding follows the same two-phase contract as SkillCatalog.register: the corpus swap lands first, then the batch is embedded. Only genuinely new or re-worded skills are embedded — an unchanged id keeps its vector, so reloading an unchanged catalog costs no embedding calls at all. If the embedding pass fails, the new corpus is already live and BM25 still ranks it; semantic search reports EmbeddingsNotBuilt until a later pass succeeds.

A concurrent operation refuses the call outright rather than applying it half-way, so two overlapping reloads can never blend into one corpus. Because the swap is the synchronous half, that refusal throws at the call site rather than rejecting the returned promise. Note that any in-flight SkillCatalog.searchAsync can trigger it, including a plain BM25 one — registry busy is retryable and not exclusive to dense work.

Parameters

Returns

PendingReplace

The counts, already final, over a promise for the embedding pass — see PendingReplace. .added/.removed can be read before that pass settles, but the value must still always be awaited (or .catch()-ed), or an embedding failure becomes an unhandled rejection.

search()

search(query, topK, origin?, method?): SkillHit[]

Search the catalog synchronously with BM25. A "semantic"/"hybrid" call throws synchronously with guidance to use SkillCatalog.searchAsync.

Parameters

Returns

SkillHit[]

Up to topK BM25 hits, best-first with ties broken by skill id. Semantic/dense/hybrid methods throw migration guidance; use SkillCatalog.searchAsync for those methods.

searchAsync()

searchAsync(query, topK, origin?, method?): Promise<SkillHit[]>

Search with any retrieval method without blocking the Node.js event loop.

Parameters

Returns

Promise<SkillHit[]>

size()

size(): number

Number of registered skills (distinct ids). searchCapabilitiesTool uses this to decide whether to advertise a skills bucket at all.

Returns

number

The count.

SkillRegistry

Typed facade over the native skill registry — the skill twin of ToolRegistry. SkillCatalog is the higher-level surface; reach for this directly only when bare metadata is enough.

Constructors

Constructor

new SkillRegistry(embedding?, method?): SkillRegistry

Create a registry with an optional embedding model and retrieval method.

Parameters

Returns

SkillRegistry

Accessors

experimentalAdaptiveRankingStatus

Get Signature

get experimentalAdaptiveRankingStatus(): AdaptiveRankingStatus

Whether adaptive usage ranking is contributing ("active"), off ("inactive"), not yet determinable ("unknown"), or paused because the embedding model changed ("paused: dim mismatch" / "paused: model mismatch"). Gate on this instead of reading stderr if you prefer.

Returns

AdaptiveRankingStatus

Methods

drainTraceEvents()

drainTraceEvents(): unknown[]

Drain captured envelopes from a "memory" sink; [] otherwise.

Returns

unknown[]

experimentalDisableAdaptiveRanking()

experimentalDisableAdaptiveRanking(): void

Turn adaptive usage ranking off: ranking returns to the base engine and the graph stops growing. The graph keeps what it learned, so re-enabling resumes rather than restarts.

Returns

void

experimentalEnableAdaptiveRanking()

experimentalEnableAdaptiveRanking(graph, options?): void

Turn on adaptive usage ranking against graph (ADR-0014).

Wires both halves: the registry ranks against the graph, and its trace sink is decorated with a learner that grows it from search-then-invoke pairs — a capability the user actually invoked after a query becomes evidence for similar queries later.

Pass the same IntentGraph to the tool and skill registries. One cluster holds both a tool and a skill edge map, so sharing gives one set of clusters with all the evidence behind it; separate graphs duplicate every cluster and split the evidence.

Only queries that match a cluster are affected — anything else ranks exactly as it would have. With a graph attached, SearchHit.score becomes a fusion score rather than a raw BM25 score, so use rank for ordering and fused to detect the scale, not the raw score.

Parameters

Returns

void

experimentalRebuildIntentGraph()

experimentalRebuildIntentGraph(): Promise<void>

Re-embed the intent graph's members under the current embedding model and replace its centroids. Call after changing the model: a graph's centroids are only comparable to queries from the model that built them, so on a swap the usage arm pauses until this runs. Members, support, and edges are preserved — only the centroids move to the new space.

Returns

Promise<void>

recordEvent()

recordEvent(event): void

Record a custom event on the local trace stream (ADR-0007).

Parameters

Returns

void

register()

register(item): Promise<void>

Register one skill or a batch, replacing any existing id in place — see ToolRegistry.register for the embed-inside contract.

Parameters

Returns

Promise<void>

search()

search(query, topK): SkillHit[]

Lexical BM25 search over skills — see ToolRegistry.search.

Parameters

Returns

SkillHit[]

searchWithMethod()

searchWithMethod(query, topK, origin, method): SkillHit[]

Synchronous search restricted to BM25 — see ToolRegistry.searchWithMethod.

Parameters

Returns

SkillHit[]

searchWithMethodAsync()

searchWithMethodAsync(query, topK, origin, method): Promise<SkillHit[]>

Search on a libuv worker — see ToolRegistry.searchWithMethodAsync.

Parameters

Returns

Promise<SkillHit[]>

searchWithOrigin()

searchWithOrigin(query, topK, origin): SkillHit[]

BM25 search with an explicit trace origin.

Parameters

Returns

SkillHit[]

setTraceSink()

setTraceSink(config): void

Replace the trace sink; subsequent events go to the new destination.

Parameters

Returns

void

ToolCatalog

In-process catalog of executable tools, ranked by the native Rust registry. The SDK's central surface: ToolCatalog.register tools (or ingest an MCP server's via registerMcpServer), ToolCatalog.search them by relevance, and ToolCatalog.invoke the chosen one. Every operation emits both an OTel span (to whatever provider is active — see telemetry.ts) and a local trace event (to the sink from ToolCatalogOptions.trace), per ADR-0007.

Example

import { ToolCatalog } from "@ratel-ai/sdk";
import { readFile } from "node:fs/promises";

const catalog = new ToolCatalog();
await catalog.register({
  id: "read_file",
  name: "read_file",
  description: "Read a file from local disk and return its textual contents.",
  inputSchema: {
    type: "object",
    properties: { path: { type: "string", description: "absolute path to the file" } },
    required: ["path"],
  },
  outputSchema: { type: "object" },
  execute: async ({ path }) => ({ contents: await readFile(path, "utf8") }),
});

const [hit] = catalog.search("read a file from disk", 5);
const result = await catalog.invoke(hit.toolId, { path: "/tmp/notes.txt" });

Constructors

Constructor

new ToolCatalog(options?): ToolCatalog

Create an empty catalog.

Parameters

Returns

ToolCatalog

Accessors

experimentalAdaptiveRankingStatus

Get Signature

get experimentalAdaptiveRankingStatus(): AdaptiveRankingStatus

Whether adaptive usage ranking is active, inactive, or paused by a model change — see the native AdaptiveRankingStatus.

Returns

AdaptiveRankingStatus

Methods

drainTraceEvents()

drainTraceEvents(): unknown[]

Drain the envelopes captured by a "memory" trace sink, emptying its buffer.

Returns

unknown[]

The captured envelopes ({ v, ts, session_id, type, ... } — the event fields are flattened alongside the envelope stamp) in record order. Always [] unless the active sink is "memory".

experimentalDisableAdaptiveRanking()

experimentalDisableAdaptiveRanking(): void

Turn adaptive usage ranking off; the graph keeps what it learned.

Returns

void

experimentalEnableAdaptiveRanking()

experimentalEnableAdaptiveRanking(graph, options?): void

Turn on adaptive usage ranking against graph (ADR-0014): the catalog ranks against what users have actually invoked after similar queries, and keeps learning as it is used.

Pass the same IntentGraph to a SkillCatalog so both learn into one set of clusters.

Set rebuildOnModelChange to auto-recover a model-mismatched graph on the next dense (semantic/hybrid) search rather than staying paused until you call experimentalRebuildIntentGraph yourself. Off by default — the rebuild is an embedding pass (cost, possible EmbedderError, and it mutates the graph).

Parameters

Returns

void

experimentalRebuildIntentGraph()

experimentalRebuildIntentGraph(): Promise<void>

Re-embed the intent graph's members under the current model and replace its centroids — call after changing the embedding model. Preserves members, support, and edges. See experimentalEnableAdaptiveRanking.

Returns

Promise<void>

get()

get(toolId): Tool | undefined

Look up a tool's searchable metadata (no executor attached).

Parameters

Returns

Tool | undefined

The metadata as registered, or undefined for an unknown id.

getExecutable()

getExecutable(toolId): ExecutableTool | undefined

Look up a tool with its executor reattached.

Parameters

Returns

ExecutableTool | undefined

A copy of the registered tool including execute, or undefined for an unknown id.

has()

has(toolId): boolean

Whether a tool with this id is registered.

Parameters

Returns

boolean

true if ToolCatalog.invoke would find an executor for it.

invoke()

invoke(toolId, args, context?): Promise<unknown>

Run a registered tool's executor. Sync-absorbing: a plain value or Promise settles through the returned promise, and a synchronous throw surfaces as a rejection — invoke never throws synchronously, including for an unknown toolId (that rejects with unknown toolId: …). An AsyncIterable is the resolved value; its instrumentation settles when the iterator completes, is cancelled, or fails.

The call is wrapped in an execute_tool OTel span and bracketed by invoke_start / invoke_end (or invoke_error, with the error message) events on the local trace stream, took_ms in wall-clock milliseconds.

Parameters

Returns

Promise<unknown>

Whatever the executor returns (resolved if it returned a promise).

invokeRaw()

invokeRaw(toolId, args, context?): unknown

Run a registered tool without erasing its immediate return shape after synchronous validation. A plain value stays plain, a promise stays a promise, and an AsyncIterable stays synchronously iterable. An async validator necessarily makes this method return a promise of the executor's result. Instrumentation settles only when that returned shape settles (including iterator completion, cancellation, or failure).

Most callers should use invoke; capability-tool bridges use this path so a host framework can observe streamed preliminary outputs.

Parameters

Returns

unknown

invokeValidatedRaw()

invokeValidatedRaw(toolId, input, context?): unknown

Execute input already parsed by validateInput, preserving its immediate scalar, promise, or AsyncIterable return shape. Framework bridges call this only after their host has run the capability tool's live validator; ordinary callers should use invoke.

Parameters

Returns

unknown

recordEvent()

recordEvent(event): void

Record a custom event on the local trace stream (ADR-0007), e.g. an upstream_register from an ingestion layer. Delivered to the sink configured at construction; a no-op sink discards it.

Parameters

Returns

void

register()

register(tools): Promise<void>

Add one tool or a batch to the catalog — the single entry point for both. Replaces an id in place when already registered (metadata, executor, and index entry; the corpus never holds a duplicate). On a "semantic"/"hybrid" catalog, embeds the batch in one pass on a libuv worker after metadata is indexed, so the event loop is never blocked; embedding errors (model load / endpoint / auth / dimension) surface here, at registration — metadata still persists even if the embedding pass that follows fails. A "bm25" catalog never loads a model and resolves as soon as metadata is indexed.

A model or dimension change is not recovered in place — construct a new catalog and re-register.

Parameters

Returns

Promise<void>

Throws

EmbedderError on a "semantic"/"hybrid" catalog when embedding fails (model load / endpoint / auth / dimension) — a DimensionMismatchError for a vector-width change. A missing execute handler throws a plain Error.

search()

search(query, topK, origin?, method?): SearchHit[]

Search the catalog. method overrides the catalog default for this call. "semantic"/"hybrid" rank against the prebuilt embedding cache and throw synchronously with guidance to use ToolCatalog.searchAsync.

Parameters

Returns

SearchHit[]

Up to topK BM25 hits, best-first with ties broken by tool id. Semantic/dense/hybrid methods throw migration guidance; use ToolCatalog.searchAsync for those methods.

searchAsync()

searchAsync(query, topK, origin?, method?): Promise<SearchHit[]>

Search with any retrieval method without blocking the Node.js event loop.

Parameters

Returns

Promise<SearchHit[]>

validateInput()

validateInput(toolId, input): InputValidationResult | Promise<InputValidationResult>

Run a registered framework validator without executing the tool. A tool without one succeeds with its input unchanged. The returned success value is the exact input the executor should receive, including any defaults or root-level transformation.

Parameters

Returns

InputValidationResult | Promise<InputValidationResult>

ToolRegistry

Typed facade over the native tool registry: metadata-only indexing and retrieval, with the SDK's public embedding config and an async, batch-aware register. ToolCatalog layers executors, OTel spans, and defaults on top; reach for this directly only when bare metadata (no executors) is enough.

Constructors

Constructor

new ToolRegistry(embedding?, method?): ToolRegistry

Create a registry with an optional embedding model and retrieval method.

Parameters

Returns

ToolRegistry

Accessors

experimentalAdaptiveRankingStatus

Get Signature

get experimentalAdaptiveRankingStatus(): AdaptiveRankingStatus

Whether adaptive usage ranking is contributing ("active"), off ("inactive"), not yet determinable ("unknown"), or paused because the embedding model changed ("paused: dim mismatch" / "paused: model mismatch"). Gate on this instead of reading stderr if you prefer.

Returns

AdaptiveRankingStatus

Methods

drainTraceEvents()

drainTraceEvents(): unknown[]

Drain captured envelopes from a "memory" sink; [] otherwise.

Returns

unknown[]

experimentalDisableAdaptiveRanking()

experimentalDisableAdaptiveRanking(): void

Turn adaptive usage ranking off: ranking returns to the base engine and the graph stops growing. The graph keeps what it learned, so re-enabling resumes rather than restarts.

Returns

void

experimentalEnableAdaptiveRanking()

experimentalEnableAdaptiveRanking(graph, options?): void

Turn on adaptive usage ranking against graph (ADR-0014).

Wires both halves: the registry ranks against the graph, and its trace sink is decorated with a learner that grows it from search-then-invoke pairs — a capability the user actually invoked after a query becomes evidence for similar queries later.

Pass the same IntentGraph to the tool and skill registries. One cluster holds both a tool and a skill edge map, so sharing gives one set of clusters with all the evidence behind it; separate graphs duplicate every cluster and split the evidence.

Only queries that match a cluster are affected — anything else ranks exactly as it would have. With a graph attached, SearchHit.score becomes a fusion score rather than a raw BM25 score, so use rank for ordering and fused to detect the scale, not the raw score.

Parameters

Returns

void

experimentalRebuildIntentGraph()

experimentalRebuildIntentGraph(): Promise<void>

Re-embed the intent graph's members under the current embedding model and replace its centroids. Call after changing the model: a graph's centroids are only comparable to queries from the model that built them, so on a swap the usage arm pauses until this runs. Members, support, and edges are preserved — only the centroids move to the new space.

Returns

Promise<void>

recordEvent()

recordEvent(event): void

Record a custom event on the local trace stream (ADR-0007). Throws on an object that doesn't parse as a known trace event.

Parameters

Returns

void

register()

register(item): Promise<void>

Register one tool or a batch, replacing any existing id in place — the corpus never holds a duplicate. On a "semantic"/"hybrid" registry, embeds the whole batch in one pass on a libuv worker after metadata is indexed, so the event loop is never blocked; awaiting surfaces embedding errors here. A "bm25" registry resolves as soon as metadata is indexed and never loads a model.

Parameters

Returns

Promise<void>

search()

search(query, topK): SearchHit[]

Lexical BM25 search: up to topK hits, best-first with ties broken by id. Model-free and infallible; records the query on the local trace stream with origin "direct".

Parameters

Returns

SearchHit[]

searchWithMethod()

searchWithMethod(query, topK, origin, method): SearchHit[]

Synchronous search restricted to BM25; "semantic"/"hybrid" throw with guidance to use ToolRegistry.searchWithMethodAsync.

Parameters

Returns

SearchHit[]

searchWithMethodAsync()

searchWithMethodAsync(query, topK, origin, method): Promise<SearchHit[]>

Search on a libuv worker; supports "bm25", "semantic", and "hybrid".

Parameters

Returns

Promise<SearchHit[]>

searchWithOrigin()

searchWithOrigin(query, topK, origin): SearchHit[]

BM25 search with an explicit trace origin; ranking is unaffected.

Parameters

Returns

SearchHit[]

setTraceSink()

setTraceSink(config): void

Replace the trace sink; subsequent events go to the new destination.

Parameters

Returns

void

Interfaces

AdaptedBase

The framework-shaped surface every adapter inherits from the core. Adapters add their idioms via RatelAdapter.extend; universal capability lives here.

Type Parameters

Properties

skills

readonly skills: SkillCatalog

The shared skill catalog (skills are framework-neutral).

tools

readonly tools: AdaptedToolCollection<TTool>

This view's handle over the shared catalog, in the framework's tool shape.

Methods

modelTools()

modelTools(): Record<string, TTool>

The model-facing toolset in the framework's shape: this view's passthroughs plus the three capability tools run through the adapter's expose codec. Fresh objects per call — take it once per agent instance and reuse it, so the prompt cache survives. Tools registered later are still discoverable (the capability tools search the live catalog); only a passthrough registered later needs a fresh modelTools() to reach the model.

Returns

Record<string, TTool>

recall()

recall(query): Promise<TMessage[]>

Rank query and return the synthetic search_capabilities message pair in the framework's shape (origin "direct"), or [] when nothing matched (spending no call id). Pure: it builds fresh messages and never mutates a host array.

Parameters

Returns

Promise<TMessage[]>

AdaptedToolCollection

An adapted view's handle over the same shared catalog, speaking the framework's tool shape. Registration runs the adapter's ingest codec; first registration of an id wins across every view of the core, including ids claimed by framework-local passthroughs, so repeated calls are idempotent.

register/has are framework-aware (register takes the framework's tool shape; has also covers this view's passthroughs); get/search/invoke are at parity with ToolCollection — they read and run the shared catalog in its neutral shapes, so they're catalog-only: a passthrough is provider-executed and un-indexed, so has reports it but get returns undefined, search never ranks it, and invoke can't run it.

Type Parameters

Properties

catalog

readonly catalog: ToolCatalog

The shared catalog itself — the unguarded driver-level escape hatch.

Methods

get()

get(id): Tool | undefined

A catalog tool's searchable metadata, or undefined (incl. for a passthrough).

Parameters

Returns

Tool | undefined

has()

has(id): boolean

Whether this id is registered — in the catalog or as this view's passthrough.

Parameters

Returns

boolean

invoke()

invoke(id, args): Promise<unknown>

Execute a catalog tool by id with the args object (not a passthrough).

Parameters

Returns

Promise<unknown>

register()

register(tools): Promise<void>

Ingest framework tools (keyed by tool id) into the shared catalog. Async, with the same semantics as ToolCollection.register: ids are validated and ingested synchronously (a reserved id throws at the call site), then the returned promise resolves when the batch is indexed and, on a semantic/hybrid core, embedded — rejecting if embedding fails. await it before a dense search.

Parameters

Returns

Promise<void>

search()

search(query, topK, method?): SearchHit[]

Rank the shared catalog for query synchronously (host-driven, origin "direct"). BM25 only — semantic/hybrid throws with a pointer to searchAsync. topK is clamped to [1, 50] (invalid values fall back to 5); passthroughs are never ranked. Drop to catalog for an unclamped search.

Parameters

Returns

SearchHit[]

searchAsync()

searchAsync(query, topK, method?): Promise<SearchHit[]>

Rank the shared catalog for query with any retrieval method off the event loop (origin "direct"). Same topK clamp as search; passthroughs are never ranked. await register(...) first so a dense tool is embedded.

Parameters

Returns

Promise<SearchHit[]>

AdaptiveRankingStatus

SDK-facing view of whether adaptive usage ranking is contributing. status is "active" | "inactive" | "unknown" | "paused: dim mismatch" | "paused: model mismatch"; built/active/dimMismatch are set only when paused.

Properties

active?

optional active?: string

When paused: the currently active embedding model (or its dimension). Absent unless paused.

built?

optional built?: string

When paused: the embedding model (or its dimension) the graph's centroids were built with. Absent unless paused.

dimMismatch?

optional dimMismatch?: boolean

When paused: true if the mismatch is a dimension difference, false if it is a same-dimension model-identity difference. Absent unless paused.

status

status: string

One of "active" | "inactive" | "unknown" | "paused: dim mismatch" | "paused: model mismatch".

CapabilitiesSearchOptions

Options for runCapabilitiesSearch.

Properties

origin?

optional origin?: SearchOrigin

Who initiated the search — stamped on the gateway_search trace event and the ratel.search span. Default "agent" (a model-synthesized call); the host-driven recall path passes "direct".

skillCatalog?

optional skillCatalog?: SkillCatalog

Catalog the skills bucket is ranked from (and whose declared tool deps ride in).

topKSkills?

optional topKSkills?: number

Max skills bucket size; capped at 50, default 3; invalid values fall back to the default.

topKTools?

optional topKTools?: number

Max tools bucket size; capped at 50, default 5 (same as the tool); 0, negative, or non-integer values fall back to the default.

upstreamServers?

optional upstreamServers?: readonly UpstreamServerInfo[]

Upstream-server metadata attached to the matching result groups.

CapabilitySkillHit

One ranked skill in the skills bucket of SearchCapabilitiesResult.

Properties

description

description: string

The skill's description, compacted to ~160 chars for the listing.

score

score: number

Retrieval score from the skill catalog's search (BM25 by default).

skillId

skillId: string

Skill id to pass to get_skill_content.

CapabilityToolGroup

Tool hits grouped by upstream server. The group key is the <server>__ id prefix (a plain, un-prefixed tool id groups under itself); description and instructions are attached when a matching UpstreamServerInfo was provided.

Properties

hits

hits: CapabilityToolHit[]

The server's ranked hits, in overall result order.

server

server: object

The owning server: its name, plus optional description/instructions metadata.

description?

optional description?: string

The server's one-line summary, when known.

instructions?

optional instructions?: string

The server's usage instructions, when known.

name

name: string

Server name (the <server>__ prefix of the group's tool ids).

CapabilityToolHit

One ranked tool in the tools bucket of SearchCapabilitiesResult.

Properties

description

description: string

The tool's description, as registered.

inputSchema

inputSchema: Record<string, unknown>

The tool's input JSON Schema, so the model can call it without another lookup.

score

score: number

Retrieval score from the tool catalog's search (scale depends on the catalog's method — BM25 by default), or 0 when the tool was pulled in as a matched skill's declared dependency rather than by the query itself.

toolId

toolId: string

Catalog id to pass to invoke_tool (<server>__<tool> for MCP-proxied tools).

CatalogRegistration

A framework tool ingested into the catalog: what an adapter's RatelAdapter.ingest returns for an executable tool. The core registers it verbatim (id/name are the app's tool key), so the schemas are the SDK's public JSONSchema7 spelling and adapters need no casts.

Properties

description

description: string

Retrieval ranks on this; resolve dynamic descriptions at ingest time.

inputSchema

inputSchema: JSONSchema7

Input JSON Schema (the catalog's native spelling).

outputSchema?

optional outputSchema?: JSONSchema7

Output JSON Schema; defaults to { type: "object" } when omitted.

validateInput?

optional validateInput?: InputValidator

Framework-native parser retained in the shared catalog. Capability-tool exposure delegates to this live parser, so every adapted view observes native replacements and root-level transformations.

Methods

execute()

execute(input, context?): unknown

Runs the tool through the capability funnel with args and optional opaque adapter context. An adapter that supports live framework context tags it in expose and validates that private tag here before unwrapping it; a missing or foreign tag must take the framework's context-free fallback.

Parameters

Returns

unknown

ExecutableTool

A tool the catalog can both retrieve and run: the searchable metadata of a Tool (id, name, description, schemas) plus its Executor. The unit ToolCatalog.register accepts and ToolCatalog.getExecutable returns.

Extends

• Tool

Properties

description

description: string

What the tool does and when to use it — the main ranking signal.

Inherited from

Tool.description

execute

execute: Executor

Runs the tool. Called by ToolCatalog.invoke with args and optional context.

id

id: string

Unique id, the registry key. Re-registering an existing id replaces the entry in place. MCP-proxied tools use the <server>__<tool> convention.

Inherited from

Tool.id

inputSchema

inputSchema: JSONSchema7

JSON Schema of the arguments. Property names and their descriptions (nested included) are indexed for ranking.

Inherited from

Tool.inputSchema

name

name: string

Callable name (typically the same as id for local tools); indexed for ranking both whole and split on snake_case/camelCase boundaries.

Inherited from

Tool.name

outputSchema

outputSchema: JSONSchema7

JSON Schema of the result; indexed the same way as inputSchema.

Inherited from

Tool.outputSchema

validateInput?

optional validateInput?: InputValidator

Shared parser used before execution and by model-facing host bridges.

InvokeToolError

A generic invoke_tool error whose original target failure is available to framework adapters.

Properties

[INVOKE_TOOL_ERROR_CAUSE]

readonly [INVOKE_TOOL_ERROR_CAUSE]: unknown

Original thrown value, hidden from enumeration and serialization.

error

error: string

Human-readable failure passed to the model.

isError

isError: true

Stable discriminator used by generic capability hosts.

InvokeToolToolOptions

Options for invokeToolTool.

Properties

onUnauthorized?

optional onUnauthorized?: (upstream) => void | Promise<void>

Notified when the underlying tool throws UnauthorizedError, with the upstream name inferred from the toolId.

Parameters

Returns

void | Promise<void>

JSONSchema7

Properties

$comment?

optional $comment?: string

$defs?

optional $defs?: object

Index Signature

[key: string]: JSONSchema7Definition

See

• https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.2.4
• https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#appendix-A

$id?

optional $id?: string

$ref?

optional $ref?: string

$schema?

optional $schema?: string

additionalItems?

optional additionalItems?: JSONSchema7Definition

additionalProperties?

optional additionalProperties?: JSONSchema7Definition

allOf?

optional allOf?: JSONSchema7Definition[]

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7

anyOf?

optional anyOf?: JSONSchema7Definition[]

const?

optional const?: JSONSchema7Type

contains?

optional contains?: JSONSchema7Definition

contentEncoding?

optional contentEncoding?: string

contentMediaType?

optional contentMediaType?: string

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-8

default?

optional default?: JSONSchema7Type

definitions?

optional definitions?: object

Index Signature

[key: string]: JSONSchema7Definition

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-9

dependencies?

optional dependencies?: object

Index Signature

[key: string]: string[] | JSONSchema7Definition

description?

optional description?: string

else?

optional else?: JSONSchema7Definition

enum?

optional enum?: JSONSchema7Type[]

examples?

optional examples?: JSONSchema7Type

exclusiveMaximum?

optional exclusiveMaximum?: number

exclusiveMinimum?

optional exclusiveMinimum?: number

format?

optional format?: string

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7

if?

optional if?: JSONSchema7Definition

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6

items?

optional items?: JSONSchema7Definition | JSONSchema7Definition[]

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4

maximum?

optional maximum?: number

maxItems?

optional maxItems?: number

maxLength?

optional maxLength?: number

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3

maxProperties?

optional maxProperties?: number

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5

minimum?

optional minimum?: number

minItems?

optional minItems?: number

minLength?

optional minLength?: number

minProperties?

optional minProperties?: number

multipleOf?

optional multipleOf?: number

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2

not?

optional not?: JSONSchema7Definition

oneOf?

optional oneOf?: JSONSchema7Definition[]

pattern?

optional pattern?: string

patternProperties?

optional patternProperties?: object

Index Signature

[key: string]: JSONSchema7Definition

properties?

optional properties?: object

Index Signature

[key: string]: JSONSchema7Definition

propertyNames?

optional propertyNames?: JSONSchema7Definition

readOnly?

optional readOnly?: boolean

required?

optional required?: string[]

then?

optional then?: JSONSchema7Definition

title?

optional title?: string

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10

type?

optional type?: JSONSchema7TypeName | JSONSchema7TypeName[]

See

https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1

uniqueItems?

optional uniqueItems?: boolean

writeOnly?

optional writeOnly?: boolean

McpServerHandle

What registerMcpServer returns: the ingested ids plus lifecycle control.

Properties

close

close: () => Promise<void>

Close the underlying MCP client connection. The proxied tools stay in the catalog but invoking them after close fails.

Returns

Promise<void>

serverInstructions

serverInstructions: string | undefined

The usage instructions the server declared during the MCP initialize handshake, or undefined if it declared none. Useful as UpstreamServerInfo.instructions when building capability tools.

toolIds

toolIds: string[]

Namespaced ids in upstream list order (all pages). Duplicate names may appear more than once; ToolCatalog.register keeps the last row.

Ratel

One ratel(config) core: a single ToolCatalog + SkillCatalog

• recall-id counter shared by every Ratel.adaptTo view. Genuinely usable standalone — register native tools on Ratel.tools, hand the model Ratel.modelTools, rank with Ratel.recall — and adaptable on top for a framework's native shapes.

Properties

skills

readonly skills: SkillCatalog

The shared skill catalog — exposed raw (skills are framework-neutral and need no ingest codec), so it is the unguarded escape hatch at parity with ToolCollection.catalog: its search top-K is not clamped. Use recall for a clamped, capability-shaped skills ranking.

tools

readonly tools: ToolCollection

Handle over the shared tool catalog (native shapes, guarded).

Methods

adaptTo()

adaptTo<A>(adapter): AdaptedRatel<A>

Adapt the core to a framework, inferring its tool/message types and helpers.

Type Parameters

Parameters

Returns

AdaptedRatel<A>

modelTools()

modelTools(): Record<string, ExecutableTool>

The three capability tools (search_capabilities, invoke_tool, get_skill_content) in native shape, for framework-free hosts. All three are always advertised — the set never depends on registration order, so the prompt cache survives; loading a skill from an empty catalog returns a structured error, not a missing tool. Fresh objects per call: take it once and reuse it. Tools and skills registered later are still discoverable.

Returns

Record<string, ExecutableTool>

recall()

recall(query): Promise<SearchCapabilitiesResult | null>

Rank query into the canonical search_capabilities result (origin "direct", top-K from recallTopK), or null when nothing matched. A pure query: no call id is minted — ids exist only on the adapted views, whose synthetic message pairs need them. Ranks whatever is registered and (on a dense core) embedded now — await r.tools.register(...) first.

Parameters

Returns

Promise<SearchCapabilitiesResult | null>

RatelAdapter

The framework boundary: one complementary package per framework implements this so Ratel speaks that framework's native tool and message shapes. The three codecs (ingest / expose / recallMessages) are the whole contract; extend adds framework idioms. The core owns all state and guards, so an adapter is ~three pure functions.

Type Parameters

Properties

name

readonly name: string

Names the adapter in error messages (and, once adapter packages emit it, in the ratel.adapter telemetry attribute — stamping is deferred to them per ADR-0013).

Methods

expose()

expose(tool): TTool

Ratel capability tool → framework tool. Context-aware adapters wrap the framework's complete live execution context in a private, stable tag before passing it as the capability executor's optional second argument.

Parameters

Returns

TTool

extend()?

optional extend(base): TExt

Framework-idiomatic helpers, merged onto the adapted object.

Parameters

Returns

TExt

ingest()

ingest(id, tool): CatalogRegistration | "passthrough"

Framework tool → catalog registration, or "passthrough" for tools the catalog can't execute (provider-executed) that must stay eagerly exposed.

Parameters

Returns

CatalogRegistration | "passthrough"

recallMessages()

recallMessages(ref, recall): TMessage[]

Synthetic recall pair in the framework's message shape.

Parameters

Returns

TMessage[]

RatelConfig

Construction options for ratel. Shared by every adapter view of the core.

Properties

embedding?

optional embedding?: EmbeddingSpec

Embedding model backing "semantic"/"hybrid" retrieval, forwarded to both catalogs — see ToolCatalogOptions.embedding. A string is a local model directory path; every other source is a keyed object ({ huggingface }, { ollama }, { url, model, apiKeyEnv }). Omit to use the built-in default model. await r.tools.register(...) awaits the embedding pass and rejects if it fails, so errors surface at registration.

method?

optional method?: SearchMethod

Default retrieval method for the tool and skill catalogs (default "bm25", model-free).

recallTopK?

optional recallTopK?: number

Max tools each host-driven recall returns: capped at 50; 0, negative, or non-integer values fall back to the default 5.

trace?

optional trace?: TraceSinkConfig

Local trace-stream destination for both catalogs (default: discard).

RecallRef

The identity of one synthetic recall call, handed to RatelAdapter.recallMessages.

Properties

callId

callId: string

Unique call id from the core's private counter (never a transcript position).

query

query: string

The recall query (the last user turn's text, in the AI SDK adapter).

RegisterMcpServerOptions

Options for registerMcpServer.

Properties

name

name: string

Namespace for the server's tools inside the catalog: each tool is registered as <name>__<toolName>. Also the server name that trace events and result groups report for these tools.

transport

transport: Transport

An MCP client transport for the server (e.g. StdioClientTransport, StreamableHTTPClientTransport, or an InMemoryTransport pair in tests). registerMcpServer connects it; it must not be connected already.

ReplaceOutcome

What a SkillRegistry.replaceAll changed, counted by id. updated covers any field edit (including a body-only rewrite); unchanged ids are identical to what was registered and keep their cached embedding.

Properties

added

added: number

Ids in the new corpus that were not in the old one.

removed

removed: number

Ids in the old corpus that are absent from the new one.

unchanged

unchanged: number

Ids present in both with identical content.

updated

updated: number

Ids present in both whose content differs in any field.

SearchCapabilitiesOptions

Options for searchCapabilitiesTool.

Properties

advertiseSkills?

optional advertiseSkills?: boolean

Override the skills clause in the tool description. Default: present only when the skill catalog is non-empty at build time. Hosts that always expose get_skill_content (the ratel() facade) pass true so the description is byte-identical regardless of when the first skill registers.

upstreamServers?

optional upstreamServers?: readonly UpstreamServerInfo[]

Upstream MCP servers to advertise in the tool description and result groups.

SearchCapabilitiesResult

Result shape of the search_capabilities tool: two independently-ranked buckets with separate top-K budgets. Scores are comparable within a bucket, not across the two (tools and skills are indexed as different text shapes).

Properties

skills

skills: CapabilitySkillHit[]

Skill hits — playbooks to load via get_skill_content.

tools

tools: object

Executable tool hits, grouped by upstream server.

groups

groups: CapabilityToolGroup[]

Groups in ranking order (a server appears where its best hit ranked).

SearchHit

One ranked tool from a registry search, best-first.

Properties

fused

fused: boolean

true when score is an RRF score (ordering-only) rather than the raw method score: the usage arm fused into this search, or the method is hybrid. Uniform across one result list; lets a caller detect the scale.

rank

rank: number

0-based position in this result list (best is 0). Stable across methods and across the fused switch — the field to order or threshold on.

score

score: number

Relevance score; higher is better, ties break by id ascending. Its scale depends on the method (raw BM25 / cosine / RRF) AND on fused — with adaptive ranking a matched query returns small RRF scores while an unmatched one on the same catalog returns the raw score. Order by rank and branch on fused; treat score as a within-list hint only.

toolId

toolId: string

Id of the matched tool, as registered.

SearchToolHit

Deprecated

Use CapabilityToolHit.

Properties

description

description: string

The tool's description, as registered.

inputSchema

inputSchema: Record<string, unknown>

The tool's input JSON Schema.

score

score: number

Retrieval score from the catalog's search (BM25 by default).

toolId

toolId: string

Catalog id to pass to invoke_tool.

SearchToolsGroup

Deprecated

Use CapabilityToolGroup.

Properties

hits

hits: SearchToolHit[]

The server's ranked hits, in overall result order.

server

server: object

The owning server: its name, plus optional description/instructions metadata.

description?

optional description?: string

The server's one-line summary, when known.

instructions?

optional instructions?: string

The server's usage instructions, when known.

name

name: string

Server name (the <server>__ prefix of the group's tool ids).

SearchToolsResult

Deprecated

Use SearchCapabilitiesResult (the tools.groups field).

Properties

groups

groups: SearchToolsGroup[]

Tool hits grouped by upstream server, in ranking order.

SearchToolsToolOptions

Deprecated

Use SearchCapabilitiesOptions.

Properties

upstreamServers?

optional upstreamServers?: readonly UpstreamServerInfo[]

Upstream MCP servers to advertise in the tool description and result groups.

Skill

A reusable playbook: instructions the agent reads and follows, in contrast to a Tool it executes. Name, description, and tags are indexed for ranking; the body is the dispatch payload, deliberately excluded from the index so it can't drown the description's term weights.

Properties

body?

optional body?: string

The full instructions (Markdown) returned on load — the dispatch payload, never indexed for ranking. Optional (defaults to "") — parity with the Python SDK's default body.

description

description: string

What the skill covers and when to reach for it — the main ranking signal.

id

id: string

Unique id, the registry key. Re-registering an existing id replaces the entry in place.

metadata?

optional metadata?: Record<string, string[]>

Free-form, non-indexed context for higher layers — e.g. { stacks: ["react"] } for the push ranker to boost by project context.

name

name: string

Human-readable name; indexed for ranking both whole and split on snake_case/camelCase boundaries.

tags?

optional tags?: string[]

Author-declared labels and task phrases ("frontend", "login form"); indexed for ranking. Optional (defaults to []) — a minimal Skill(id, name, description) is valid, in parity with the Python SDK.

tools?

optional tools?: string[]

Ids of tools this skill's instructions call; surfaced into the search_capabilities tools bucket — not indexed as query terms.

SkillCatalogOptions

Construction options for SkillCatalog.

Properties

embedding?

optional embedding?: EmbeddingSpec

Embedding model for semantic/hybrid retrieval — see ToolCatalogOptions.embedding. Retained for asynchronous overrides.

method?

optional method?: SearchMethod

Default retrieval method for search (default "bm25").

trace?

optional trace?: TraceSinkConfig

Local trace stream destination (default: discard). See TraceSinkConfig.

SkillHit

One ranked skill from a registry search, best-first — the skill twin of SearchHit, with the same score semantics per method.

Properties

fused

fused: boolean

true when score is an RRF score — as on SearchHit.fused.

rank

rank: number

0-based position in this result list — as on SearchHit.rank.

score

score: number

Relevance score; scale depends on the method and on fused, as on SearchHit.score. Order by rank, branch on fused.

skillId

skillId: string

Id of the matched skill, as registered.

Tool

A tool's searchable metadata: what the registry indexes and what a search hit resolves back to. Execution lives a layer up (the SDK's ToolCatalog pairs each Tool with its executor).