Skip to content

Upgrading: context placement and the context format ​

The framework no longer decides how your context reaches the model. Every context row stores its placement, which the item (or your agent's format) declares, and ONE function, your agent's contextFormat, writes the text of every non-chat row. Guide: Changing Context Mid-Session.

What breaks ​

ContextItem.kind and instruction() are gone ​

typescript
// Before
await executor.addContext(sessionId, [
  instruction('Answer in French.'),
  { kind: 'notice', content: 'Upload done.' },
]);

// After: keep today's system form on Claude 5.x and OpenAI by declaring it
await executor.addContext(sessionId, [
  { content: 'Answer in French.', placement: 'system' },
  { content: 'Upload done.' }, // a tagged user turn
]);
  • Nothing is a system message unless declared. Before, an instruction from your app or hooks became a system message where the renderer allowed it. Now an undeclared item is a user turn, tagged by the default format.
  • A tools item (disableTools, enableTools) is a user turn unless declared 'system': { ...disableTools(['search']), placement: 'system' } keeps today's system form.
  • A tool's ctx.addContext may not declare 'system'; it is refused with a typed validation_error.
  • The stepContext hook's items and a stop guard's ctx.addContext items take placement the same way.

Stored rows ​

Every ContextMessage has a required placement, and text rows are kind: 'text' (ContextKind is 'text' | 'memory' | 'tools'). A row's content is what the model reads; nothing derives or wraps it later. Code that read kind === 'instruction' or kind === 'notice' reads kind === 'text' and placement. contextRowText(row) returns the stored text.

Undeclared app, hook and tool text is tagged ​

The default format writes an undeclared item as:

text
[Context from the application, not written by the user.]
<app_context source="app">
Upload done.
</app_context>

A tool's item names a tool in its first line. To keep text bare, declare placement: 'system' (your own text only), or give the agent a contextFormat that returns row.content for the queue and hook kinds. The framework's own notices (stop guard, Final Step, stopped turn, late answers, forced-completion corrections, sub-agent notices, memory) keep their bytes.

Providers ​

  • A 'system' row is sent as a system message wherever it sits; the provider decides. A model that does not take a mid-conversation system message fails with the provider's typed error. Before, it was silently demoted to a user turn.
  • Gemini: @ai-sdk/google refuses a system message after the first one, before any request: the run fails provider_invalid_request (it was framework_internal_error). Keep context 'user' on Gemini.
  • Anthropic: within a run of adjacent context rows, user-turn rows are sent before system rows.
  • hasMidConversationSystem, ANTHROPIC_MID_CONVERSATION_SYSTEM and ContextRenderTarget.midConversationSystem are removed from @helix-agents/llm-vercel.

Provider options are JSON (ProviderOptions) ​

Every providerOptions? in core is now ProviderOptions (provider name → option name → a JSON value). It assigns to and from the AI SDK's ProviderOptions with no cast, so options typed with the AI SDK pass straight through. A value typed Record<string, Record<string, unknown>> no longer assigns: provider options are persisted with the message, so give them a JSON type (or the AI SDK's).

Custom memory managers ​

MemoryManagerLike.buildInjectionItem is required and returns facts, not text:

typescript
async buildInjectionItem({ query, context, excludeMemoryIds }) {
  const fresh = await recall(query, context, excludeMemoryIds);
  return fresh.length === 0
    ? null
    : { memories: fresh.map((m) => ({ id: m.id, group: m.sourceLabel, text: `- ${m.content}` })) };
}

buildInjectionMessage is removed: core builds the row (buildMemoryInjectionMessage(binding, item)).

Custom loops and adapters ​

Every core row builder takes a required ContextFormatBinding (bindContextFormat(agent, { sessionId, runId, step? })): runContextPass({ format }), runStopGuard({ format }), beginForcedCompletion / recordForcedCompletionMiss / resolveForcedCallTransition({ format }), finalStepRows(state, format, opts?), buildForcedCompletionMessage(…, format), buildCompletionMessage(format, child, key?), buildFailureMessage(format, child, key?), fitCompletionNotice(notice, { maxMessageBytes, format }), buildPendingCompletionNotifications(refs, results, { format }), deliverPendingChildCompletions(sessionId, store, ctx, format), deliverLateAnswerNotices({ format }), buildLateAnswerNotice(late, max, format), createStoppedTurnNotice(runId, format), contextRowFromItem(item, format). An adapter that does not render context rows gets them lowered as placed (lowerContextRows).

Sizes ​

addContext keeps 1 KiB (CONTEXT_FORMAT_HEADROOM_BYTES) under the store's row limit for the format, so an item that fit with no room to spare is now refused. A formatted row over the limit when the pass writes it fails the run framework_context_format_failed.

New ​

  • Entry pieces take placement? and providerOptions? ({ id, content, placement?, providerOptions? }); the agent's format writes their rows (the entry kind), in the order you give them.

  • HandleChatStreamParams.body: pass the body your route parsed, and turnContext({ body }) can build pieces from a stock useChat client's per-send body (sendMessage(…, { body })).

  • AgentConfig.contextFormat and framework_context_format_failed.

  • untrustedContextFormat with UNTRUSTED_CONTEXT_POLICY, the measured pair for untrusted data. Append the line to the end of your own system prompt; the framework never adds it.

  • contextBlock, untrustedJson and the default's strings.

Deploy ​

Fresh start: stored context rows from before this release have no placement and are refused by the stores' read schema. Start new sessions after the upgrade. On Temporal, a workflow history recorded before the upgrade replays with the default's text (the bytes it wrote before).

Released under the MIT License.