Agent.Context

class Context class

The conversation context: an ordered message list (a private array — read it through length/at/messages()/iteration, change it through the methods below), optionally NAMED (id/name) and LOGGED to a session file in dir (save). Crash safety is the owner's: an Agent flushes its context from a process-finish hook.

Defined in lib/context/store.js

ContentType = Object.freeze({…}) constant

Content block discriminators.

Defined in lib/context/types.js

EventType = Object.freeze({…}) constant

The full normalized event vocabulary.

Defined in lib/context/events.js

FALLBACK_CONTEXT_WINDOWS = Object.freeze({…}) constant

Curated context windows for the CURRENT OpenAI tier, from the models docs (developers.openai.com/api/docs/models, reviewed 2026-09-28 — the gpt-6 family lists 1.05M; o-series 200K). OpenAI's API-key surface publishes NO window anywhere (/models, /models/{id}, and the response envelope are all bare — probed with ai-tmp/probe-openai-models.js), so the status gauge reads this table while a lazy registry lookup (lib/env/model-windows.js) fills the endpoint's model cache. Any provider-published or looked-up value outranks it. Review when a new tier ships.

Defined in lib/context/usage.js

MIME_BY_EXTENSION = Object.freeze({…}) constant

Context-owned media-type map and byte detection for content blocks.

Defined in lib/context/mime.js

MessageType = Object.freeze({…}) constant

Numeric message types. 0 is reserved.

Defined in lib/context/types.js

TOKENS_PER_WORD = 4 / 3 constant

tokens ≈ words × 4/3 (token-per-word likelihood ratio)

Defined in lib/context/usage.js

assemblyCallbacks(assembler) function

Build the camelCase callback set used by Context to feed response events to an assembler. Includes callbacks for start, text/thinking block events, tool-call events, done, and error.

assembler ReturnType<typeof createAssembler>

Assembler receiving the events; no default is provided.

Returns Object<string, function(object): void> — Callbacks keyed by names such as `onStart`, `onTextDelta`, `onDone`, and `onError`.

Effects — Creates a new callback object; each callback delegates to assembler.consume and therefore mutates that assembler.

Throws — Throws if assembler is missing or does not provide consume, or if event processing throws when a callback is invoked.

Defined in lib/context/assemble.js

createAssembler() function

Create an assembler that folds normalized response events into one assistant message. Events mutate the in-progress message; valid message snapshots on start, done, or error replace it. Unknown event types are ignored, and malformed tool-call JSON is retained as raw text. The returned message remains partial until completion and is exposed by reference.

Returns {consume: (event: object) => void, message: () => object} — The event consumer and accessor for the current message.

Throws — Creating the assembler does not intentionally throw. Its returned `consume` method can propagate errors from malformed events or message mutations; JSON parse errors for tool arguments are suppressed.

Defined in lib/context/assemble.js

normalizeCallbacks(callbacks = {…}, binding = {…}) function

Build the full callback set for a binding.

[callbacks={}] Object

consumer-supplied callbacks, keyed by camelCase callback name. A function is used as-is; explicit `false` or `null` selects a no-op; an omitted or `undefined` callback gets the binding default.

[binding={}] Object

binding-appropriate default handlers.

[binding.onData] (event:object)=>void

receives every event whose callback was omitted (stdout replacement)

[binding.onLog] (line:string)=>void

receives error reports (stderr replacement)

[binding.onTerminal] (event:object)=>void|false|null

completes the binding; called for `done` and `error` even when the consumer supplied its own terminal callback. `false` or `null` disables this additional call.

Returns Object — Complete callback set keyed by camelCase names.

Throws — {Error} If an invoked binding handler throws; its error propagates to the caller.

Defined in lib/context/events.js

binaryContent(path, buffer) function

Build a canonical base64 binary Context block without exposing the source path.

path string

Non-empty local path; only its basename is retained.

buffer Uint8Array

Binary data to encode.

Returns {type: "binary", mimetype: string, filename: string, content: string} — A block containing the basename, detected media type, and base64 data.

Throws — {TypeError} If path is not a non-empty string or buffer is not a Uint8Array.

Defined in lib/context/mime.js

contentIndexer() function

Create a per-request content-block indexer for a provider translator. of reuses an index for a previously seen wire-item key, while next always reserves a fresh index; indexes are dense and follow first appearance.

Returns {of: (key: *) => number, next: () => number} — Indexing operations.

Defined in lib/context/assemble.js

textContent(text) function

Wrap a value's string representation in a text content block.

text *

Value converted with `String()`.

Returns TextContent — A block with `type: ContentType.Text` and the converted text.

Throws — {*} Propagates a thrown value encountered during string conversion.

Defined in lib/context/types.js

callbackName(eventName) function

Map an event name to its camelCase callback name. "text_delta" -> "onTextDelta"; "tool_call_start" -> "onToolCallStart".

eventName string

normalized event name to convert.

Returns string — The corresponding camelCase callback name.

Throws — {TypeError} If `eventName` does not support `split` (for example, it is not a string).

Defined in lib/context/events.js

dispatch(set, event) function

Dispatch one event through a normalized callback set. Validates the event before invoking its matching callback; callback errors propagate to the caller.

set Object

callback set returned by `normalizeCallbacks`.

event object

normalized response event to dispatch.

Returns void

Throws — {TypeError} If `event` is invalid or the callback cannot be invoked; errors thrown by the callback also propagate unchanged.

Defined in lib/context/events.js

isResponseEvent(event) function

Is this a well-formed normalized response event (a known type; indexed events carry a non-negative integer contentIndex)?

event *

value to check.

Returns boolean — `true` for an object with a known event type and, for indexed events, a non-negative integer `contentIndex`; otherwise `false`.

Defined in lib/context/events.js

validateResponseEvent(event) function

Validate a normalized response event (used by IO to check connector output). Returns the same object; throws on violation.

event *

value to validate.

Returns object — The same event object when it is valid.

Throws — {TypeError} If the value is not a well-formed normalized response event.

Defined in lib/context/events.js

fallbackContextWindow(model) function

The curated fallback window for one model id, or null: an exact key, then the longest table prefix the id starts with ("gpt-6-sol" -> "gpt-6", "o3-2025-04-16" -> "o3").

model *

bare model id; non-string or empty values are rejected

Returns number|null — matching fallback token window, or `null` when none

Defined in lib/context/usage.js

appendMessage(context, message, { merge = true } = {…}) function

Append a message to a caller-owned context, MERGING when possible: the message's own adjacent same-sub-type blocks fold first; when the context's last message is mergeable with it (same type, no linkage), their content concatenates (and re-folds) instead of appending a new message. Consecutive same-type text messages — queued user input, repeated /system, a cancel-partial assistant followed by the next turn's — become ONE message, so the context (and every replay of it) shows one merged block per sub-type, not a chain of fragments. Mutates the array in place.

context Array<object>

Caller-owned context array, mutated in place.

message object

Message or metadata record to append.

Returns object|undefined — The stored message (the previous message when merged, otherwise the appended value), or `undefined` when an empty message is skipped.

Throws — {TypeError} If context/message validation fails.

Throws — {TypeError} If folding or merge comparisons fail during processing.

Defined in lib/context/merge.js

assistantMessage(content = []) function

Create an assistant message using the supplied content blocks.

[content=[] Content[]

] - Ordered content blocks; defaults to an empty array.

Returns Message — An assistant message whose content is the supplied array; no validation or copying is performed.

Defined in lib/context/types.js

errorText(msg) function

Get the presentation text of a normalized assistant failure; tool-result boolean errors are distinct and produce an empty string.

msg *

Value whose error field is inspected.

Returns string — The error string, `error.message`, or an empty string.

Defined in lib/context/validate.js

fileMessage(path, buffer) function

Wrap one local file's bytes in the canonical user-message content structure.

path string

Non-empty local file path passed to {@link binaryContent}.

buffer Uint8Array

File bytes passed to {@link binaryContent}.

Returns {type: 2, content: Array<{type: "binary", mimetype: string, filename: string, content: string}>} — A user message containing a single binary content block.

Throws — {TypeError} If either argument fails {@link binaryContent}'s validation.

Defined in lib/context/mime.js

hasContent(msg) function

Has this message any CONTENT a provider can consume? A block with no payload — a text/thinking block whose text is empty, a block reduced to its discriminator alone — is not content; an empty content array is not content either. Chat-completions dialects serialize an empty assistant message as content: null and providers 400 the whole request over it (corrupted sessions), so emptiness is a hard contract, not a style point.

msg *

Value whose `content` blocks are inspected.

Returns boolean — True if at least one block carries provider-consumable content.

Defined in lib/context/validate.js

hasError(msg) function

Does this message report a FAILED RESPONSE? A provider or transport failure is normalized as the response message carrying error — a text string or {message, retry} for timed rate limits — beside whatever content arrived before it (possibly none: the error is then its whole payload). A tool result's boolean error: true is not one: that is the tool's own (answered) failure.

msg *

Value whose normalized response error is inspected.

Returns boolean — True for a nonempty error string or nonempty `error.message`.

Defined in lib/context/validate.js

isRecord(msg) function

Test whether a value is a metadata record: a non-array object with a string type (not a numeric message type). Records may share context and session files with messages; they are not messages and are skipped by message validators. Other components pass them through unmerged or filter them from provider-bound contexts as appropriate.

msg *

Value to test.

Returns boolean — True when `msg` carries a string `type`.

Defined in lib/context/validate.js

rebuildMessage(msg) function

Rebuild a message from recognized schema fields only — the stale provider/cache identifier cleanup. See the module header for the field policy.

msg object

Message to validate and rebuild.

Returns object — A new message containing recognized fields only.

Throws — {TypeError} If the message is invalid.

Defined in lib/context/edit.js

systemMessage(text) function

Create a system message containing one text block made from the given value.

text *

Value converted to a string for the text block.

Returns Message — A system message with one text content block.

Throws — {*} Propagates a thrown value encountered during string conversion.

Defined in lib/context/types.js

userMessage(text, metadata = undefined) function

Create a user message from plain text or an existing ordered block array. Non-array input is converted to a text block; array input is used as-is. If supplied, metadata is spread over the message and can override its fields.

text string|Content[]|*

Plain-text value to convert, or an array of content blocks to preserve.

[metadata=undefined] *

Optional value whose enumerable own properties are spread last onto the message.

Returns Message — The resulting user message.

Throws — {*} Propagates a thrown value from text conversion or metadata getters/spread.

Defined in lib/context/types.js

isMessage(msg) function

Test whether a value has the core message shape: a non-array object with a numeric type and an array content.

msg *

Value to test.

Returns boolean — True when `msg` has the core message shape.

Defined in lib/context/validate.js

validateMessage(msg, at = "message") function

Validate a message's CORE SHAPE, throwing on a violation. Returns the SAME object reference — metadata is never copied, stripped, or reordered. Emptiness is deliberately NOT part of the shape: appendMessage WARNS and drops an empty incoming message, and IO DROPS empty messages from every provider-bound context (no dialect can carry one), while a merge that consumed an incoming message's whole payload into the previous message may legitimately leave it empty inside the live array.

msg *

Value to validate.

[at="message"] string

Address hint for error messages (e.g. "context[2]").

Returns object — The same `msg` reference, unchanged.

Throws — {TypeError} If `msg` is not a non-array object with a numeric `type` and array `content`; the error includes the address hint.

Defined in lib/context/validate.js

parseContext(input) function

Parse buffered CLI input into a context array using the shared grammar. First, the entire input is parsed as JSON; if that is an array, it is returned unchanged. Otherwise, each nonblank line is parsed independently: message objects and valid messages in arrays are included, while other values become user text messages containing the original line.

input string

Complete stdin text after EOF; there is no default.

Returns Array<object> — The resulting context array. This is synchronous and returns no Promise.

Throws — {TypeError} If input is not a string and line processing attempts to call `split` on it.

Effects — Pure parser: does not read stdin or otherwise perform I/O. JSON parse errors are caught and treated as non-JSON input.

Defined in lib/context/parse.js

isContext(ctx) function

Test whether a value is a context array containing only core-shaped messages and/or metadata records.

ctx *

Value to test.

Returns boolean — True when `ctx` is such an array; an empty array passes.

Defined in lib/context/validate.js

validateContext(ctx) function

Validate a context array, allowing metadata records and validating every other entry as a message. Returns the same array reference without mutation.

ctx *

Value to validate as a context.

Returns Array — The same `ctx` array, unchanged.

Throws — {TypeError} If `ctx` is not an array or any non-record entry fails message validation; entry errors identify their context index.

Defined in lib/context/validate.js

detectMime({ path, buffer } = {…}) function

Determine a media type from a filename extension, then recognized leading bytes.

Returns string — The matching media type, or `application/octet-stream` when neither input identifies a supported type.

Throws — {TypeError} If options is `null` and therefore cannot be destructured.

Defined in lib/context/mime.js

mimetypeOf(block) function

Return a content block's media type, preferring its non-empty mimetype field and then its non-empty mime field.

block Object|null|undefined

Block to inspect; nullish values are allowed.

Returns string|undefined — The selected media type, or `undefined` when neither field is a non-empty string.

Throws — {*} Propagates a thrown value from a getter for `mimetype` or `mime`; accessors may be read more than once.

Defined in lib/context/types.js

estimateTokens(text) function

Estimate a token count for text, rounding the heuristic up to a whole token. Non-string inputs produce zero.

text *

value to estimate when it is a string

Returns number — estimated whole-token count

Defined in lib/context/usage.js

estimateContextTokens(context = []) function

Estimated token count of a whole context (the input side of a request — also the live "window consumption" readout when no provider-reported count exists yet). Counts words per block: the historical one-giant-string + word-array version allocated several full copies of the context per call, per frame. Reuses per-block scans only while the current text/argument string values are unchanged; live in-place field and content-array edits are observed on the next call.

[context=[] Array

] - context messages; each message's supported content-block text and arguments are counted

Returns number — estimated input tokens, rounded up to a whole token

Throws — {TypeError} if `context` is not iterable

Defined in lib/context/usage.js

usageAdd(total, reported) function

Add one request report to lifetime usage. Sum only schema counters; recompute totalTokens; replace (and clear absent) metadata/details with the latest report.

total object

Previous totals; neither mutated nor retained.

reported *

Request usage, normalized or wire-shaped; never retained.

Returns object — New independent totals. Non-idempotent: call once per billed attempt.

Effects — None. Invalid reports are ignored; no failures for JSON input.

Defined in lib/context/usage-data.js

usageDetails(value) function

Copy bounded JSON-safe usage/plan extensions, omitting invalid values, cycles, attribution and prototype keys. Limits: 256 nodes, depth 6, 16 array entries, 1024 characters/string, 128/key and 16K total text. Truncation adds no counters.

value *

Untrusted details; neither mutated nor retained.

Returns * — Independent bounded JSON value, or undefined for unsupported input.

Effects — None. Idempotent; no failures for JSON data. Work is bounded by these limits.

Defined in lib/context/usage-data.js

estimateUsage(context = [], message) function

Estimate usage from the request context and the assembled response.

[context=[] Array

] - request messages used for input estimation

[message=undefined] object

assembled assistant message used for output estimation; its content text/arguments are concatenated before estimating

Returns {inputTokens:number, outputTokens:number, source:"estimate"} — estimated usage

Throws — {TypeError} if `context` is not iterable

Defined in lib/context/usage.js

finalizeUsage(reported, context, message) function

Normalize provider-reported usage, or fall back to estimation. Provider token counts win only as a complete pair: partial/invalid counts use estimation (no mixed token sources), retaining normalized counters, finite reported cost and bounded extensions. Input is neither mutated nor retained. Repeated calls with the same report/context/message are idempotent; no side effects.

reported *

connector-extracted usage; accepted only when both inputTokens and outputTokens (or known aliases) are nonnegative finite numbers. Known aliases are consumed; unknown fields become bounded latest-report details

[context=undefined] Array

request context for fallback input estimation; when omitted, the estimator's empty-array default applies

[message=undefined] object

assembled message for fallback output estimation

Returns {inputTokens:number, outputTokens:number, totalTokens:number, source:string, cost?:number, [key: string]: *} — independent canonical snapshot with reported or estimated token counts

Throws — {TypeError} if fallback estimation is needed and `context` is not iterable

Defined in lib/context/usage.js

usageHeaders(headers, { exclude = [] } = {…}) function

Capture bounded unrepresented rate-limit header extensions, excluding unrelated headers.

headers Headers|object

Response headers exposing forEach; neither retained nor mutated; absent input returns an empty map.

[options={}] object

Header filtering options.

[options.exclude=[] string[]

] Header names already represented as quotas, case-insensitive.

Returns Object<string, string> — Independent bounded header map. Idempotent, no side effects.

Throws — {TypeError} If exclude is not an array of strings; correct options before retrying.

Defined in lib/context/usage.js

usageNormalize(reported) function

Normalize a request's usage without estimating tokens. Canonical fields outrank aliases; cache/reasoning detail fields outrank legacy root fields, reasoning outranks thinking. All token counts include cached/reasoning subsets, not extras. Unknown extensions become bounded latest-report details; consumed aliases disappear.

reported *

Provider data; neither mutated nor retained. Invalid fields are omitted.

Returns object — Independent snapshot with nonnegative counters, finite reported cost, derived totalTokens, optional serviceTier/inferenceGeo and bounded details. Idempotent.

Effects — None. No failures for JSON input; detail processing is bounded.

Defined in lib/context/usage-data.js

wordCount(text) function

Count runs of non-whitespace characters without allocating a split array. Non-string and empty inputs produce zero.

text *

value to count when it is a string

Returns number — number of whitespace-separated words

Defined in lib/context/usage.js