Shape

interface UtilsAPI {
  measure(input: MeasureInput): number
  now(): number
}

type MeasureInput =
  | string
  | Message
  | Message[]
  | Attachment
  | Attachment[]

Overview

ctx.utils provides a minimal set of generic, model-agnostic helpers available in every strategy context.

These utilities:

• do not depend on any specific LLM
• do not require external services
• behave consistently across environments

They are primarily used during context construction and strategy execution.

Methods

measure(input)

Returns a normalized cost estimate for the given input.

This function supports text, messages, and attachments, and is designed for budgeting and relative comparison during context construction.

input: MeasureInput

Supported inputs include:

• raw text (string)
• a single message (Message)
• an array of messages (Message[])
• a single attachment (Attachment)
• an array of attachments (Attachment[])

Return: number

Important:

• The result is an approximation
• It does not correspond to exact token usage of any specific model
• It is intended for relative comparison (e.g. “this is larger than that”)

Behavior:

• text → estimated by length
• messages → aggregates content and attachments
• attachments → estimated using type-specific heuristics (e.g. image, document, audio)

Example:

const cost = ctx.utils.measure(ctx.history.recent(12))

if (cost > 8000) {
  // reduce memory injection
}

now()

Returns the current Unix timestamp in milliseconds.

Return: number

Example:

const timestamp = ctx.utils.now()

Recommended Use

Use ctx.utils for:

• estimating context cost before building prompts
• controlling memory or slot injection based on budget
• recording timestamps in metadata

Notes

• measure() provides a normalized cost estimate, not an exact token count
• results may vary slightly depending on runtime heuristics
• strategies should use it for decision-making, not precise accounting

ctx.utils is intentionally minimal to keep the strategy environment predictable and stable.