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
// 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
instructionfrom 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
toolsitem (disableTools,enableTools) is a user turn unless declared'system':{ ...disableTools(['search']), placement: 'system' }keeps today's system form. - A tool's
ctx.addContextmay not declare'system'; it is refused with a typedvalidation_error. - The
stepContexthook's items and a stop guard'sctx.addContextitems takeplacementthe 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:
[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/googlerefuses a system message after the first one, before any request: the run failsprovider_invalid_request(it wasframework_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_SYSTEMandContextRenderTarget.midConversationSystemare 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:
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?andproviderOptions?({ id, content, placement?, providerOptions? }); the agent's format writes their rows (theentrykind), in the order you give them.HandleChatStreamParams.body: pass the body your route parsed, andturnContext({ body })can build pieces from a stockuseChatclient's per-send body (sendMessage(…, { body })).AgentConfig.contextFormatandframework_context_format_failed.untrustedContextFormatwithUNTRUSTED_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,untrustedJsonand 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).