ContextBuilder

SUPPORT · interface · Type contract

Compiled builder. It holds no request state and may be shared across invocations.

Import

TypeScript

import type { ContextBuilder } from '@jangts/agent-core/support';

JavaScript

/** @typedef {import('@jangts/agent-core/support').ContextBuilder} ContextBuilder */

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/support, @jangts/agent-core/support/context.

Definition

interface ContextBuilder<Input>

Type parameters

Type parameter	Constraint	Default type
Input	—	—

Field structure

Field	Type	Required	Description
fragments	(input: Input) => ContextFragment[]	Required	Produces the fragments for one input, after transforms.
build	(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "fragments" | "maxInputChars">) => BuiltContext	Required	Assembles and validates the plan into messages with usage accounting.
plan	(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "fragments" | "maxInputChars">) => ContextPlan	Required	Produces the unassembled plan without running the budget boundary.

Member index

Member	Purpose
fragments	Produces the fragments for one input, after transforms.
build	Assembles and validates the plan into messages with usage accounting.
plan	Produces the unassembled plan without running the budget boundary.

Member details

fragments

Produces the fragments for one input, after transforms.

ContextBuilder.fragments(input: Input): ContextFragment[]

Produces the fragments for one input, after transforms.

Parameter	Type	Passing	Description
input	Input	Required	—

Returns: ContextFragment[].

build

Assembles and validates the plan into messages with usage accounting.

ContextBuilder.build(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "fragments" | "maxInputChars">): BuiltContext

Assembles and validates the plan into messages with usage accounting.

Parameter	Type	Passing	Description
request	{ input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">	Required	—

Fields of request

Field	Type	Required	Description
input	Input	Required	See the type definition and usage context.
maxInputChars	number | undefined	Optional	See the type definition and usage context.
additionalMessages	readonly (ModelMessage & { role: "user"; })[] | undefined	Optional	Protected user messages (for example image inputs); text counts toward the same budget.
originalFragments	readonly ContextFragment[] | undefined	Optional	Trusted originals for structural mutation auditing; never sent to the model.
mutableFragmentIds	readonly string[] | undefined	Optional	Explicit value-mutation allowance when originals are supplied.

Returns: BuiltContext.

Return value structure

Field	Type	Required	Description
messages	ModelMessage[]	Required	Messages in final model order.
fragmentUsage	ContextFragmentUsage[]	Required	Per-fragment accounting in the same order as the fragments were merged.
inputChars	number	Required	Total counted characters across messages and usage.
maxInputChars	number	Required	Budget the assembly was validated against; Infinity means unbounded.

plan

Produces the unassembled plan without running the budget boundary.

ContextBuilder.plan(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "fragments" | "maxInputChars">): ContextPlan

Produces the unassembled plan without running the budget boundary.

Parameter	Type	Passing	Description
request	{ input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">	Required	—

Fields of request

Field	Type	Required	Description
input	Input	Required	See the type definition and usage context.
maxInputChars	number | undefined	Optional	See the type definition and usage context.
additionalMessages	readonly (ModelMessage & { role: "user"; })[] | undefined	Optional	Protected user messages (for example image inputs); text counts toward the same budget.
originalFragments	readonly ContextFragment[] | undefined	Optional	Trusted originals for structural mutation auditing; never sent to the model.
mutableFragmentIds	readonly string[] | undefined	Optional	Explicit value-mutation allowance when originals are supplied.

Returns: ContextPlan.

Return value structure

Field	Type	Required	Description
fragments	readonly ContextFragment[]	Required	Read-only. Fragments in the order supplied by the App; assembly preserves it.
maxInputChars	number	Required	Character budget Core validates after assembly.
additionalMessages	readonly (ModelMessage & { role: "user"; })[] | undefined	Optional	Protected user messages (for example image inputs); text counts toward the same budget.
originalFragments	readonly ContextFragment[] | undefined	Optional	Trusted originals for structural mutation auditing; never sent to the model.
mutableFragmentIds	readonly string[] | undefined	Optional	Explicit value-mutation allowance when originals are supplied.

Examples

• Context assembly: configure stable metadata once: Support binds fragment metadata, formatting, and order in advance, and requests supply only the changing business input.

Configure once, then supply only question and history

Beginner · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
type Input = { question: string; history: readonly { role: string; content: string }[] };
const builder = Support.defineContextFragments<Input>([
  { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
    role: 'user', format: input => input.question },
  { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
    role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const context = builder.build({ input: { question: '服务状态？', history: [] } });
console.log(context.messages);

JavaScript

import { Support } from '@jangts/agent-core';
const builder = Support.defineContextFragments([
    { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
        role: 'user', format: input => input.question },
    { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
        role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const context = builder.build({ input: { question: '服务状态？', history: [] } });
console.log(context.messages);

The same builder produces a plan in advance

Configuration · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
type Input = { question: string; history: readonly { role: string; content: string }[] };
const builder = Support.defineContextFragments<Input>([
  { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
    role: 'user', format: input => input.question },
  { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
    role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const input = { question: '服务状态？', history: [] };
const plan = builder.plan({ input });
const expanded = builder.fragments(input);
console.log(plan.maxInputChars, expanded.map(fragment => fragment.id));
const largerRequest = builder.build({ input, maxInputChars: 2000 });
console.log(largerRequest.maxInputChars);

JavaScript

import { Support } from '@jangts/agent-core';
const builder = Support.defineContextFragments([
    { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
        role: 'user', format: input => input.question },
    { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
        role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const input = { question: '服务状态？', history: [] };
const plan = builder.plan({ input });
const expanded = builder.fragments(input);
console.log(plan.maxInputChars, expanded.map(fragment => fragment.id));
const largerRequest = builder.build({ input, maxInputChars: 2000 });
console.log(largerRequest.maxInputChars);

Related policy source

• Assembly order, dependency snapshots, and request budget overrides

Related definitions

• BuiltContext
• ContextFragment
• ContextPlan