context

Classes

TokenCounter

Defined in: packages/nexus-agents/src/context/token-counter.ts:86

Universal token counter supporting multiple providers.

Provides accurate token counting via provider APIs (Anthropic, Gemini) or local tiktoken (OpenAI), with fallback to character-based estimation.

Example

const counter = new TokenCounter({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  googleApiKey: process.env.GOOGLE_AI_API_KEY,
});

// Count via Anthropic API
const result = await counter.countAnthropic(messages, 'claude-sonnet-4');

// Count via local tiktoken
const openaiResult = counter.countOpenAI('Hello world', 'gpt-4o');

// Offline estimation
const estimate = counter.estimate('Some text');

Implements

• ITokenCounter

Constructors

Constructor

new TokenCounter(config?): TokenCounter;

Defined in: packages/nexus-agents/src/context/token-counter.ts:100

Creates a new TokenCounter instance.

Parameters

config?

TokenCounterConfig = {}

Token counter configuration

Returns

TokenCounter

Methods

clearCache()

clearCache(): void;

Defined in: packages/nexus-agents/src/context/token-counter.ts:289

Clear the token count cache.

Returns

void

Implementation of

ITokenCounter.clearCache

countAnthropic()

countAnthropic(messages, model): Promise<Result<TokenCountResult, TokenCountError>>;

Defined in: packages/nexus-agents/src/context/token-counter.ts:119

Count tokens for Anthropic/Claude models via API.

Parameters

messages

Message[]

model

string

Returns

Promise<Result<TokenCountResult, TokenCountError>>

Implementation of

ITokenCounter.countAnthropic

countGemini()

countGemini(content, model): Promise<Result<TokenCountResult, TokenCountError>>;

Defined in: packages/nexus-agents/src/context/token-counter.ts:178

Count tokens for Gemini models via API.

Parameters

content

string

model

string

Returns

Promise<Result<TokenCountResult, TokenCountError>>

Implementation of

ITokenCounter.countGemini

countOpenAI()

countOpenAI(text, model?): Result<TokenCountResult, TokenCountError>;

Defined in: packages/nexus-agents/src/context/token-counter.ts:228

Count tokens for OpenAI models using local tiktoken.

Parameters

text

string

model?

string = DEFAULT_TIKTOKEN_MODEL

Returns

Result<TokenCountResult, TokenCountError>

Implementation of

ITokenCounter.countOpenAI

dispose()

dispose(): void;

Defined in: packages/nexus-agents/src/context/token-counter.ts:368

Frees resources (tiktoken encoder). Call this when done with the counter.

Returns

void

estimate()

estimate(text): number;

Defined in: packages/nexus-agents/src/context/token-counter.ts:268

Estimate tokens offline using character-based heuristic. Uses ~4 characters per token as a general approximation.

Parameters

text

string

Returns

number

Implementation of

ITokenCounter.estimate

estimateForProvider()

estimateForProvider(text, provider): number;

Defined in: packages/nexus-agents/src/context/token-counter.ts:278

Estimate tokens for a specific provider.

Parameters

text

string

provider

TokenCounterProvider

Returns

number

getCacheStats()

getCacheStats(): {
  maxSize: number;
  size: number;
  ttlMs: number;
};

Defined in: packages/nexus-agents/src/context/token-counter.ts:296

Get current cache statistics.

Returns

{
  maxSize: number;
  size: number;
  ttlMs: number;
}

maxSize

maxSize: number;

size

size: number;

ttlMs

ttlMs: number;

Implementation of

ITokenCounter.getCacheStats

TokenCountError

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:34

Error specific to token counting operations.

Extends

• NexusError

Constructors

Constructor

new TokenCountError(message, options?): TokenCountError;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:35

Parameters

message

string

options?

cause?

Error

context?

Record<string, unknown>

Returns

TokenCountError

Overrides

NexusError.constructor

Properties

cause

readonly cause: Error | undefined;

Defined in: packages/nexus-agents/src/core/errors.ts:105

Inherited from

NexusError.cause

code

readonly code: ErrorCode;

Defined in: packages/nexus-agents/src/core/errors.ts:103

Inherited from

NexusError.code

context

readonly context: Record<string, unknown> | undefined;

Defined in: packages/nexus-agents/src/core/errors.ts:104

Inherited from

NexusError.context

message

message: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

NexusError.message

name

name: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from

NexusError.name

stack?

optional stack?: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

NexusError.stack

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:67

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

NexusError.stackTraceLimit

Methods

toJSON()

toJSON(): SerializedError;

Defined in: packages/nexus-agents/src/core/errors.ts:121

Serializes the error to a JSON-safe object.

Returns

SerializedError

Inherited from

NexusError.toJSON

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:51

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

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

NexusError.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:55

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

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

Inherited from

NexusError.prepareStackTrace

Interfaces

ITokenCounter

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:94

Interface for token counting operations.

Methods

clearCache()

clearCache(): void;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:132

Clear the token count cache.

Returns

void

countAnthropic()

countAnthropic(messages, model): Promise<Result<TokenCountResult, TokenCountError>>;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:101

Count tokens for Anthropic/Claude models via API.

Parameters

messages

Message[]

Messages to count tokens for

model

string

Model identifier (e.g., ‘claude-sonnet-4’)

Returns

Promise<Result<TokenCountResult, TokenCountError>>

Promise with token count result

countGemini()

countGemini(content, model): Promise<Result<TokenCountResult, TokenCountError>>;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:112

Count tokens for Gemini models via API.

Parameters

content

string

Text content to count tokens for

model

string

Model identifier (e.g., ‘gemini-2.0-flash’)

Returns

Promise<Result<TokenCountResult, TokenCountError>>

Promise with token count result

countOpenAI()

countOpenAI(text, model?): Result<TokenCountResult, TokenCountError>;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:120

Count tokens for OpenAI models using local tiktoken.

Parameters

text

string

Text to count tokens for

model?

string

Model identifier (default: ‘gpt-4o’)

Returns

Result<TokenCountResult, TokenCountError>

Token count result (synchronous, local)

estimate()

estimate(text): number;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:127

Estimate tokens offline using character-based heuristic.

Parameters

text

string

Text to estimate tokens for

Returns

number

Estimated token count

getCacheStats()

getCacheStats(): {
  maxSize: number;
  size: number;
  ttlMs: number;
};

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:137

Get current cache statistics.

Returns

{
  maxSize: number;
  size: number;
  ttlMs: number;
}

maxSize

maxSize: number;

size

size: number;

ttlMs

ttlMs: number;

TokenCounterConfig

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:48

Configuration for the token counter.

Properties

anthropicApiKey?

optional anthropicApiKey?: string;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:50

Anthropic API key (optional, required for Anthropic counting)

cacheTtlMs?

optional cacheTtlMs?: number;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:56

Cache TTL in milliseconds (default: 5 minutes)

googleApiKey?

optional googleApiKey?: string;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:52

Google API key (optional, required for Gemini counting)

maxCacheSize?

optional maxCacheSize?: number;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:54

Maximum cache entries (default: 1000)

TokenCountResult

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:66

Token counting result with metadata.

Properties

cached

cached: boolean;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:70

Whether the result was from cache

count

count: number;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:68

Number of tokens

model?

optional model?: string;

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:74

Model used (if applicable)

provider

provider: TokenCounterProvider | "estimate";

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:72

Provider used for counting

Type Aliases

TokenCounterProvider

type TokenCounterProvider = typeof TokenCounterProvider[keyof typeof TokenCounterProvider];

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:19

Supported model families for token counting.

Variables

TokenCounterProvider

const TokenCounterProvider: {
  ANTHROPIC: "anthropic";
  GEMINI: "gemini";
  OPENAI: "openai";
};

Defined in: packages/nexus-agents/src/context/token-counter-types.ts:19

Supported model families for token counting.

Type Declaration

ANTHROPIC

readonly ANTHROPIC: "anthropic" = 'anthropic';

GEMINI

readonly GEMINI: "gemini" = 'gemini';

OPENAI

readonly OPENAI: "openai" = 'openai';

Functions

createTokenCounter()

function createTokenCounter(config?): TokenCounter;

Defined in: packages/nexus-agents/src/context/token-counter.ts:392

Creates a TokenCounter instance with the specified configuration.

Parameters

config?

TokenCounterConfig = {}

Token counter configuration

Returns

TokenCounter

Configured TokenCounter instance

Example

const counter = createTokenCounter({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  googleApiKey: process.env.GOOGLE_AI_API_KEY,
});