> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime utilities

> Public runtime utilities signatures and configuration in @agentium/core 4.0.0.

Import these **11 exports** from `@agentium/core`. Read the [runtime utilities guide](/agents/overview) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## assertHostAllowed

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/path-safety.ts)

```typescript theme={null}
/**
 * Assert a URL's host is in the allowlist, throwing `PathSecurityError` if not.
 */
export declare function assertHostAllowed(url: string, allowedHosts?: string[]): void;
```

## canonicalSafeJoin

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/path-safety.ts)

```typescript theme={null}
/** Resolve links, including the nearest existing parent of a new file.
 * This prevents static symlink escapes, not hostile concurrent filesystem replacement.
 */
export declare function canonicalSafeJoin(baseDir: string, relPath: string, allowMissing?: boolean): Promise<string>;
```

## countMessagesTokens

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/token-counter.ts)

```typescript theme={null}
/**
 * Count total tokens across an array of messages.
 */
export declare function countMessagesTokens(messages: ChatMessage[], modelId?: string): number;
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage).

## countMessageTokens

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/token-counter.ts)

```typescript theme={null}
/**
 * Count tokens for a ChatMessage (content + per-message overhead).
 */
export declare function countMessageTokens(msg: ChatMessage, modelId?: string): number;
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage).

## countTokens

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/token-counter.ts)

```typescript theme={null}
/**
 * Count tokens in a text string.
 *
 * When `gpt-tokenizer` is installed, returns exact BPE token count.
 * Otherwise, uses a model-family-aware character ratio that is
 * calibrated to slightly over-estimate (safe for budget enforcement).
 *
 * @param text - The text to count tokens for
 * @param modelId - Optional model identifier for calibrated fallback ratio
 */
export declare function countTokens(text: string, modelId?: string): number;
```

## hasExactTokenizer

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/token-counter.ts)

```typescript theme={null}
/**
 * Returns true when a real tokenizer is loaded (not using heuristic).
 * Useful for logging accuracy warnings.
 */
export declare function hasExactTokenizer(): boolean;
```

## isHostAllowed

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/path-safety.ts)

```typescript theme={null}
/**
 * Returns true when a hostname (or full URL) is allowed by an allowlist.
 *
 * Allowlist entries match the hostname exactly OR as a suffix (so `*.example.com`
 * is achieved by listing `example.com` and the matcher will accept any sub-domain).
 *
 * When `allowedHosts` is `undefined` or empty, returns true (no restriction).
 */
export declare function isHostAllowed(urlOrHost: string, allowedHosts?: string[]): boolean;
```

## PathSecurityError

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/path-safety.ts)

```typescript theme={null}
/**
 * Thrown when a path traversal, symlink escape, or other path-safety violation is detected.
 */
export declare class PathSecurityError extends Error {
    constructor(message: string);
}
```

## RetryConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/retry.ts)

```typescript theme={null}
export interface RetryConfig {
    maxRetries: number;
    initialDelayMs: number;
    maxDelayMs: number;
    retryableErrors?: (error: unknown) => boolean;
}
```

## safeJoin

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/path-safety.ts)

```typescript theme={null}
/**
 * Join a base directory with a relative path, ensuring the result is contained
 * within the base directory. Detects classic traversal attempts (`../../etc/passwd`),
 * absolute-path escapes, and embedded control characters / null bytes that some
 * filesystems treat specially.
 *
 * Does NOT resolve symlinks - callers that need symlink-aware safety should use
 * `fs.realpath` after this check.
 */
export declare function safeJoin(baseDir: string, relPath: string): string;
```

## withRetry

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/utils/retry.ts)

```typescript theme={null}
export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;
```

Related: [`RetryConfig`](/api-reference/core/utils#retryconfig).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.