@benkhz/context-manager

A vanilla JS class that manages LLM conversation context end-to-end. Zero runtime dependencies.

Installation

npm install @benkhz/context-manager

Quick start

import { AIContextManager, openaiPreset } from '@benkhz/context-manager'

const mgr = new AIContextManager({
  endpoint: 'https://api.openai.com/v1/chat/completions',
  model:    'gpt-4o',
  headers:  { Authorization: `Bearer ${process.env.OPENAI_KEY}` },
  hooks: {
    ...openaiPreset,
  },
})

const reply = await mgr.send('What is the capital of France?')
console.log(reply.content) // "The capital of France is Paris."

Design decisions

| Concern | Decision | Rationale | |---|---|---| | Provider agnosticism | Caller supplies formatRequest + parseResponse hooks | No lock-in; presets ship for OpenAI and Anthropic as reference | | Context compaction | Manager POSTs to the same endpoint with a summarise prompt | Automatic; onCompact hook overrides for custom logic | | Reactive state | setState / getState / subscribe — callbacks fire synchronously | Familiar, zero magic, easy to test | | Tool loop cap | 10 iterations max | Guards against infinite loops without blocking legitimate multi-step reasoning | | Context sizing | Character count approximation | Token counting requires a tokenizer dep; chars are close enough for limit-triggering |

Constructor

new AIContextManager(config)

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | required | URL to POST every LLM request to | | hooks | object | required | See Hooks | | model | string | — | Passed through to formatRequest | | maxTokens | number | — | Passed through to formatRequest | | contextLimit | number | 80_000 | Char count that triggers auto-compaction | | compactKeepLast | number | 6 | Messages preserved verbatim after compaction | | injectSummary | boolean | true | Auto-prepend the latest summary as a system message on every LLM request. Set false to place it yourself via context.summary in formatRequest. | | headers | object | {} | Extra HTTP headers on every fetch call |

Hooks

All hooks live in config.hooks. Only formatRequest and parseResponse are required.

Required

formatRequest(context, config) → RequestBody

Converts the internal context snapshot into the HTTP request body.

// context shape
{
  messages: [{ role, content, toolCalls?, toolCallId? }],
  tools:    [{ name, schema: { description, parameters } }],
  summary:  string | null,
}

// config shape (your constructor options + per-call system override)
{ endpoint, model, maxTokens, headers, system? }

parseResponse(rawJson) → ParsedResponse

Converts the raw HTTP response JSON into the internal shape.

// must return
{
  content:    string,                              // assistant text
  stopReason: string,                              // e.g. 'stop', 'tool_use'
  toolCalls?: [{ id, name, args }],               // present when model calls tools
}

Optional lifecycle hooks

| Hook | Signature | Description | |---|---|---| | beforeSend | (messages[]) → messages[] | Transform or filter the message array before each POST. Return the array. | | afterReceive | (parsed) → parsed | Transform the parsed response before tool/message processing. | | onCompact | (overflow[], currentSummary) → string \| void | Return a summary string to override the LLM-generated one. | | onToolCall | (name, args) → args \| void | Intercept before a tool runs. Return new args to override. | | onToolResult | (name, result) → result | Transform a tool result before appending to context. | | onError | (error, phase) → void | Called on any error. phase is 'send', 'compact', or 'tool'. | | onStateChange | (key, oldVal, newVal) → void | Observe every state mutation globally. | | onContextLimit | (charCount, limit) → 'compact' \| 'truncate' \| 'error' | Choose what happens when the context limit is hit. Defaults to 'compact'. |

Messaging API

const reply = await mgr.send('your message')
// → { role: 'assistant', content: string }

await mgr.send('follow-up', { system: 'You are a pirate.' })

await mgr.compact()

Tool API

mgr.addTool(
  'getWeather',
  {
    description: 'Get current weather for a city',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string', description: 'City name' } },
      required: ['city'],
    },
  },
  async ({ city }) => ({ temp: 72, unit: 'F', condition: 'sunny' })
)

mgr.removeTool('getWeather')
mgr.getTools()   // → [{ name, schema }]

Event bus

mgr.on('message:sent',     ({ message }) => ...)
mgr.on('message:received', ({ message }) => ...)
mgr.on('tool:call',        ({ name, args }) => ...)
mgr.on('tool:result',      ({ name, result }) => ...)
mgr.on('context:compact',  ({ messageCount }) => ...)
mgr.on('context:compacted',({ summary }) => ...)
mgr.on('state:change',     ({ key, oldValue, newValue }) => ...)
mgr.on('error',            ({ error, phase }) => ...)

mgr.off('message:received', handler)
mgr.once('message:received', handler)

Reactive state

mgr.setState('userId', 'u_123')
mgr.getState('userId')              // → 'u_123'

const unsub = mgr.subscribe('userId', (newVal, oldVal) => {
  console.log(`userId changed: ${oldVal} → ${newVal}`)
})
unsub()

Introspection

mgr.getMessages()        // → Message[] — full, never-pruned turn history
mgr.getActiveMessages()  // → Message[] — current LLM-facing window (post-compaction)
mgr.getSummary()         // → string | null — latest summary
mgr.getSummaries()       // → string[] — every summary ever produced, oldest first
mgr.getTools()           // → [{ name, schema }]
mgr.getContext()         // → { messages, activeMessages, summary, summaries, tools }
mgr.reset()              // clear all message/summary state — returns this

getMessages() always returns every turn ever sent or received, even after compaction has shrunk the LLM-facing window — useful for rendering a full conversation transcript in a UI. getActiveMessages() returns what's actually being sent to the model right now.

Presets

import { openaiPreset, anthropicPreset } from '@benkhz/context-manager'

// OpenAI / Azure / Ollama / LM Studio
const mgr = new AIContextManager({
  hooks: {
    ...openaiPreset,
    beforeSend: msgs => msgs.filter(m => m.content),
  },
})

// Anthropic Messages API
const mgr = new AIContextManager({
  hooks: { ...anthropicPreset },
})

Context compaction

The manager tracks two parallel message lists: the full history (everything ever sent or received, exposed via getMessages()) and the active window (getActiveMessages()) — the slice actually sent to the LLM, which compaction and truncation shrink. History is never pruned.

This check runs at the start of every send() call, and also between tool-call iterations within a single turn — a request that triggers several tool calls in a row can grow the active window past contextLimit well before the turn finishes, so compaction can kick in mid-turn rather than waiting for the next send().

When the character count of the active window exceeds contextLimit:

1. onContextLimit hook is called — returns 'compact' (default), 'truncate', or 'error'
2. If compact: the overflow messages are sent to the LLM with a summarise prompt
3. The summary is stored (and appended to the summary history); the last compactKeepLast active messages are kept verbatim
4. On the next request, the latest summary is auto-prepended as a system message ahead of the active window — unless injectSummary: false, in which case you place it yourself via context.summary in formatRequest

The onCompact hook can return a string to bypass the LLM call entirely.

Both compaction and truncation snap their cut point to avoid splitting a tool-call/tool-result pair across the boundary — the kept window never starts with an orphaned tool message.

Open decisions

• Token counting — currently approximated via character count. A future tokenizer option could accept a (messages) => number fn for more accurate limiting.
• Streaming — send() is request/response only.
• Persistence — getContext() returns a serialisable snapshot. A future loadContext(snapshot) method would complete the persistence story.
• Multi-modal — content is currently assumed to be string.