Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: add agent compaction triggers (#400)

Vivek029772715a37
diff --git a/.changeset/modern-compaction-triggers.md b/.changeset/modern-compaction-triggers.md
new file mode 100644
index 000000000..3f6213c08
--- /dev/null
+++ b/.changeset/modern-compaction-triggers.md
@@ -0,0 +1,7 @@
+---
+'@truefoundry/trueforge-core': minor
+'@truefoundry/trueforge': minor
+'@truefoundry/trueforge-ui': minor
+---
+
+Add context-management compaction triggers with model-aware defaults and migrate persisted legacy token thresholds.
diff --git a/benchmark/bench_matrix.py b/benchmark/bench_matrix.py
index 9f1cbe82e..0096f1489 100644
--- a/benchmark/bench_matrix.py
+++ b/benchmark/bench_matrix.py
@@ -66,7 +66,10 @@ def run_tfy(task, prompt, cap):
"dynamic_sub_agents": {"enabled": True},
"sandbox": {"enabled": True},
"context_management": {
- "compaction": {"enabled": True, "compaction_threshold_tokens": 60000},
+ "compaction": {
+ "enabled": True,
+ "trigger": {"type": "input_tokens", "value": 60000},
+ },
"large_tool_response": {"enabled": True},
},
"generative_ui": {"enabled": False},
diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdx
index 927978f07..c11644a2e 100644
--- a/docs/create-agent/overview.mdx
+++ b/docs/create-agent/overview.mdx
@@ -254,7 +254,10 @@ The `manifest` you save (or the inline `spec`) is the agent spec below — every
"ask_user_questions": { "enabled": true },
"dynamic_sub_agents": { "enabled": true },
"context_management": {
- "compaction": { "enabled": true },
+ "compaction": {
+ "enabled": true,
+ "trigger": { "type": "input_tokens", "value": 80000 }
+ },
"large_tool_response": { "enabled": true }
},
"iteration_limit": 50
@@ -330,11 +333,15 @@ Runtime behavior. Every field has a default, so `config` can be omitted entirely
#### `config.context_management`
-| Field | Default | Set via | Description |
-| ---------------------------------------- | ------- | ------- | ----------------------------------------------------- |
-| `compaction.enabled` | `true` | API | Summarize older history when context grows too large. |
-| `compaction.compaction_threshold_tokens` | `50000` | API | Context size (tokens) that triggers compaction. |
-| `large_tool_response.enabled` | `true` | API | Offload oversized tool responses to a sandbox file. |
+Compaction is enabled by default. When its `trigger` is omitted, it runs at 80% of the configured model's context
+length, or at 50,000 input tokens when that context length is unavailable.
+
+| Field | Default | Set via | Description |
+| ----------------------------------- | --------------------------- | ------- | --------------------------------------------------- |
+| `compaction.enabled` | `true` | API | Summarize older history as context grows. |
+| `compaction.trigger.type` | `input_tokens` | API | Trigger using the estimated request input size. |
+| `compaction.trigger.value` | 80% of model context length | API | Explicit input-token threshold when configured. |
+| `large_tool_response.enabled` | `true` | API | Offload oversized tool responses to a sandbox file. |
### `response_format`
diff --git a/docs/key-features/overview.mdx b/docs/key-features/overview.mdx
index 2fe789326..0a83fa9b8 100644
--- a/docs/key-features/overview.mdx
+++ b/docs/key-features/overview.mdx
@@ -147,13 +147,13 @@ This avoids two failure modes at once:
### Context compaction
-When the conversation grows longer than offloading alone can manage, the harness triggers **compaction**. Compaction is enabled by default and kicks in when the active context crosses a token threshold (default **50,000 tokens**, configurable per agent).
+When the conversation grows longer than offloading alone can manage, the harness triggers **compaction**. Compaction is enabled by default and runs at 80% of the model's context length. If that length is unavailable, the harness falls back to 50,000 input tokens. An agent can also set an explicit input-token threshold.
An LLM generates a structured summary of the conversation so far — the original intent, key decisions, files and artifacts, errors and fixes, and next steps — and that summary replaces the older message history in the agent's working context, freeing tokens for continued reasoning.
```mermaid
flowchart TD
- Trigger[Active context exceeds<br/>compaction_threshold_tokens] --> Compact[Compaction]
+ Trigger[Estimated input reaches<br/>the compaction trigger] --> Compact[Compaction]
Compact --> Summary[Structured summary:<br/>intent, decisions, artifacts, next steps]
Summary --> Working[Working context = summary<br/>+ continuation instruction]
Working --> Next[Agent continues the task]
@@ -173,7 +173,10 @@ Configuration:
"context_management": {
"compaction": {
"enabled": true,
- "compaction_threshold_tokens": 50000
+ "trigger": {
+ "type": "input_tokens",
+ "value": 80000
+ }
}
}
}
diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
index 45c11c667..175fc3f33 100644
--- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
+++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
@@ -4,7 +4,7 @@ import type { ToolSource } from '../core/mcp/IMCPServer';
import { RemoteMCP, type RemoteMcpHeaders } from '../core/mcp/RemoteMCP';
import type { ToolSelectorConfig } from '../core/mcp/ToolSelectorPolicy';
import { ToolSet } from '../core/mcp/ToolSet';
-import type { ModelParams } from '../core/runtime/AgentDefinition';
+import type { AgentDefinition, ModelParams } from '../core/runtime/AgentDefinition';
import type { AgentInfo } from '../core/runtime/AgentThread.types';
import type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
@@ -61,6 +61,7 @@ export class TurnResourceResolver<
llm: (model: string) => Promise<{
modelClient: ILLM;
defaultModelParams: ModelParams;
+ modelProperties?: AgentDefinition['modelProperties'];
}>;
/**
* MCP server name → connection details. Required to use spec.mcp_servers:
@@ -200,6 +201,7 @@ export class TurnResourceResolver<
return {
definition: {
modelClient: resolvedModel.modelClient,
+ modelProperties: resolvedModel.modelProperties,
// Sub-agents receive the delegated task as a user message; their system
// prompt is SUB_AGENT_IDENTITY (added by AgentThread), not user instructions.
instruction: agentInfo ? undefined : spec.instructions,
diff --git a/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts b/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts
index 2bb13f69e..87ef04cc9 100644
--- a/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts
+++ b/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts
@@ -31,7 +31,7 @@ export function builtinsFromSpec(input: {
capabilities.push(
contextCompaction({
definition,
- compactionThresholdTokens: config.context_management.compaction.compaction_threshold_tokens,
+ compactionThresholdTokens: config.context_management.compaction.trigger?.value,
}),
);
}
diff --git a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
index 7cbb56c2c..df5caf9f7 100644
--- a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
@@ -111,16 +111,21 @@ const MCPServerRequestSchema = z
// --- Runtime config ---
+const InputTokensCompactionTriggerSchema = z
+ .object({
+ type: z.literal('input_tokens').describe('Trigger compaction when the estimated input reaches a token limit.'),
+ value: z.number().int().positive().describe('Estimated input-token count that triggers compaction.'),
+ })
+ .strict()
+ .openapi('InputTokensCompactionTrigger');
+
const CompactionSettingsSchema = z
.object({
enabled: z.boolean().default(true).describe('Summarize older history when context grows too large. Default: true.'),
- compaction_threshold_tokens: z
- .number()
- .int()
- .positive()
- .optional()
- .describe('Context size in tokens that triggers compaction. Default: 50000.'),
+ trigger: InputTokensCompactionTriggerSchema.optional(),
})
+ .strict()
+ .describe('Uses 80% of the model context length when the explicit trigger is omitted, or 50000 tokens if unknown.')
.openapi('CompactionConfig');
const LargeToolResponseSettingsSchema = z.object({
diff --git a/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts b/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts
index 365caf0bc..46b6afd28 100644
--- a/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts
+++ b/packages/trueforge-core/src/core/capabilities/builtins/ContextCompaction.ts
@@ -11,6 +11,34 @@ import type {
} from '../AgentContextProcessor';
export const DEFAULT_CONTEXT_COMPACTION_THRESHOLD_TOKENS = 50 * 1000;
+export const DEFAULT_CONTEXT_COMPACTION_RATIO = 0.8;
+
+export function resolveCompactionThresholdTokens(input: {
+ configuredThresholdTokens: number | undefined;
+ modelContextLength: number | undefined;
+ modelParams: AgentDefinition['modelParams'];
+}): number {
+ if (input.configuredThresholdTokens !== undefined) {
+ return input.configuredThresholdTokens;
+ }
+ if (input.modelContextLength !== undefined) {
+ const ratioThreshold = Math.floor(input.modelContextLength * DEFAULT_CONTEXT_COMPACTION_RATIO);
+ const configuredMaxOutputTokens = input.modelParams?.['max_completion_tokens'] ?? input.modelParams?.['max_tokens'];
+ if (
+ typeof configuredMaxOutputTokens === 'number' &&
+ Number.isFinite(configuredMaxOutputTokens) &&
+ configuredMaxOutputTokens >= 0
+ ) {
+ const inputBudget = Math.floor(input.modelContextLength - configuredMaxOutputTokens);
+ if (inputBudget > 0) {
+ return Math.min(ratioThreshold, inputBudget);
+ }
+ }
+ // An unusable output reservation must not turn compaction into an always-on loop.
+ return ratioThreshold;
+ }
+ return DEFAULT_CONTEXT_COMPACTION_THRESHOLD_TOKENS;
+}
// https://platform.openai.com/tokenizer
const PROMPT_TOKENS = 931;
@@ -225,10 +253,11 @@ export function contextCompaction(options: {
settings?: ContextCompactionSettings | undefined;
compactionThresholdTokens?: number | undefined;
}): AgentCapability {
- const threshold =
- options.compactionThresholdTokens ??
- options.settings?.compactionThresholdTokens ??
- DEFAULT_CONTEXT_COMPACTION_THRESHOLD_TOKENS;
+ const threshold = resolveCompactionThresholdTokens({
+ configuredThresholdTokens: options.compactionThresholdTokens ?? options.settings?.compactionThresholdTokens,
+ modelContextLength: options.definition.modelProperties?.contextLength,
+ modelParams: options.definition.modelParams,
+ });
return {
preLLMProcessors: [
new ContextCompaction({
diff --git a/packages/trueforge-core/src/core/runtime/AgentDefinition.ts b/packages/trueforge-core/src/core/runtime/AgentDefinition.ts
index ae98d4581..6357c2d02 100644
--- a/packages/trueforge-core/src/core/runtime/AgentDefinition.ts
+++ b/packages/trueforge-core/src/core/runtime/AgentDefinition.ts
@@ -14,6 +14,12 @@ export type ModelParams = Record<string, unknown>;
*/
export interface AgentDefinition {
modelClient: ILLM;
+ modelProperties?:
+ | {
+ /** Maximum combined input/output context for the resolved model, when known. */
+ contextLength: number | undefined;
+ }
+ | undefined;
instruction?: string | undefined;
messages?: readonly LLMUserMessage[] | undefined;
modelParams?: ModelParams | undefined;
diff --git a/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts b/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts
index 66c1219f8..f41c1e846 100644
--- a/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts
+++ b/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts
@@ -8,10 +8,29 @@ describe('AgentSpec RuntimeConfig defaults', () => {
expect(spec.config.generative_ui).toEqual({ enabled: true });
expect(spec.config.ask_user_questions).toEqual({ enabled: true });
expect(spec.config.dynamic_sub_agents).toEqual({ enabled: true });
- expect(spec.config.context_management.compaction.enabled).toBe(true);
+ expect(spec.config.context_management.compaction).toEqual({ enabled: true });
expect(spec.config.context_management.large_tool_response.enabled).toBe(true);
});
+ it('accepts an explicit input-token compaction trigger', () => {
+ const spec = AgentSpecSchema.parse({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: {
+ enabled: true,
+ trigger: { type: 'input_tokens', value: 80_000 },
+ },
+ },
+ },
+ });
+
+ expect(spec.config.context_management.compaction).toEqual({
+ enabled: true,
+ trigger: { type: 'input_tokens', value: 80_000 },
+ });
+ });
+
it('fills generative_ui when other config fields are present', () => {
const spec = AgentSpecSchema.parse({
model: { name: 'provider/model' },
diff --git a/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts b/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
index 2e2e0c90b..b8588461b 100644
--- a/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
+++ b/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
@@ -33,6 +33,29 @@ function hasOpenUITool(capabilities: ReturnType<typeof builtinsFromSpec>): boole
return capabilities.some(cap => cap.systemToolSets?.some(ts => ts.name === OPENUI_SERVER_ID));
}
+function hasCompactionProcessor(capabilities: ReturnType<typeof builtinsFromSpec>): boolean {
+ return capabilities.some(cap => (cap.preLLMProcessors?.length ?? 0) > 0);
+}
+
+describe('builtinsFromSpec compaction', () => {
+ it('enables compaction by default', () => {
+ const capabilities = runBuiltins({
+ spec: AgentSpecSchema.parse({ model: { name: 'provider/model' } }),
+ });
+ expect(hasCompactionProcessor(capabilities)).toBe(true);
+ });
+
+ it('disables compaction from the context-management Agent Spec setting', () => {
+ const capabilities = runBuiltins({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'provider/model' },
+ config: { context_management: { compaction: { enabled: false } } },
+ }),
+ });
+ expect(hasCompactionProcessor(capabilities)).toBe(false);
+ });
+});
+
describe('builtinsFromSpec generative_ui', () => {
it('enables OpenUI with preload false when generative_ui is omitted', () => {
const capabilities = runBuiltins({
diff --git a/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts b/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
index 74a158e92..ed77de533 100644
--- a/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
+++ b/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
@@ -20,6 +20,24 @@ describe('TurnResourceResolver.resolveAgentSpec', () => {
});
describe('TurnResourceResolver.resolveAgentDefinition', () => {
+ it('allows existing model resolvers to omit an unknown context length', async () => {
+ const resolver = new TurnResourceResolver({
+ llm: () => Promise.resolve({ modelClient: makeMockILLM(), defaultModelParams: {} }),
+ mcp: () => Promise.reject(new Error('unused')),
+ mcpRequestTimeoutMs: 1_000,
+ mcpConnectTimeoutMs: 1_000,
+ logger: makeSilentLogger(),
+ });
+
+ const { definition } = await resolver.resolveAgentDefinition({
+ spec: makeAgentSpec(),
+ signal: new AbortController().signal,
+ tracing: resolver.createTracing(),
+ });
+
+ expect(definition.modelProperties).toBeUndefined();
+ });
+
it.each([
{
name: 'uses the resolved model default when the agent omits max_tokens',
@@ -39,6 +57,7 @@ describe('TurnResourceResolver.resolveAgentDefinition', () => {
Promise.resolve({
modelClient: makeMockILLM(),
defaultModelParams: resolvedModelParams,
+ modelProperties: { contextLength: 128_000 },
}),
mcp: () => Promise.reject(new Error('unused')),
mcpRequestTimeoutMs: 1_000,
@@ -59,6 +78,7 @@ describe('TurnResourceResolver.resolveAgentDefinition', () => {
});
expect(definition.modelParams?.['max_tokens']).toBe(expected);
+ expect(definition.modelProperties?.contextLength).toBe(128_000);
});
});
diff --git a/packages/trueforge-core/tests/agent-session/testHelpers.ts b/packages/trueforge-core/tests/agent-session/testHelpers.ts
index e9be2f4a6..ab81ef32f 100644
--- a/packages/trueforge-core/tests/agent-session/testHelpers.ts
+++ b/packages/trueforge-core/tests/agent-session/testHelpers.ts
@@ -37,7 +37,10 @@ export function makeAgentSpec(
dynamic_sub_agents?: { enabled?: boolean };
generative_ui?: { enabled?: boolean };
context_management?: {
- compaction?: { enabled?: boolean; compaction_threshold_tokens?: number };
+ compaction?: {
+ enabled?: boolean;
+ trigger?: { type: 'input_tokens'; value: number };
+ };
large_tool_response?: { enabled?: boolean };
};
};
@@ -51,11 +54,12 @@ export function makeAgentSpec(
ask_user_questions: { enabled: false },
dynamic_sub_agents: { enabled: false },
generative_ui: { enabled: false },
+ ...overrides.config,
context_management: {
compaction: { enabled: false },
large_tool_response: { enabled: false },
+ ...overrides.config?.context_management,
},
- ...overrides.config,
},
});
}
diff --git a/packages/trueforge-core/tests/core/capabilities/builtins/ContextCompaction.test.ts b/packages/trueforge-core/tests/core/capabilities/builtins/ContextCompaction.test.ts
new file mode 100644
index 000000000..291e0acd7
--- /dev/null
+++ b/packages/trueforge-core/tests/core/capabilities/builtins/ContextCompaction.test.ts
@@ -0,0 +1,83 @@
+import {
+ DEFAULT_CONTEXT_COMPACTION_THRESHOLD_TOKENS,
+ resolveCompactionThresholdTokens,
+} from '../../../../src/core/capabilities/builtins/ContextCompaction';
+
+describe('resolveCompactionThresholdTokens', () => {
+ it('prefers an explicit input-token trigger', () => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: 80_000,
+ modelContextLength: 200_000,
+ modelParams: { max_tokens: 150_000 },
+ }),
+ ).toBe(80_000);
+ });
+
+ it('defaults to 80% of the model context length', () => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: undefined,
+ modelContextLength: 128_001,
+ modelParams: undefined,
+ }),
+ ).toBe(102_400);
+ });
+
+ it.each([
+ { modelParams: { max_tokens: 32_768 }, name: 'max_tokens' },
+ { modelParams: { max_completion_tokens: 32_768 }, name: 'max_completion_tokens' },
+ ])('reserves the configured $name output budget', ({ modelParams }) => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: undefined,
+ modelContextLength: 128_000,
+ modelParams,
+ }),
+ ).toBe(95_232);
+ });
+
+ it('prefers max_completion_tokens over max_tokens', () => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: undefined,
+ modelContextLength: 128_000,
+ modelParams: { max_completion_tokens: 32_768, max_tokens: 64_000 },
+ }),
+ ).toBe(95_232);
+ });
+
+ it('keeps the 80% threshold when it already leaves enough output budget', () => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: undefined,
+ modelContextLength: 128_000,
+ modelParams: { max_tokens: 16_000 },
+ }),
+ ).toBe(102_400);
+ });
+
+ it.each([
+ { modelParams: { max_tokens: 128_000 }, name: 'max_tokens equal to the context length' },
+ { modelParams: { max_completion_tokens: 200_000 }, name: 'max_completion_tokens above the context length' },
+ { modelParams: { max_tokens: 127_999.5 }, name: 'max_tokens leaving less than one whole input token' },
+ ])('falls back to the 80% threshold when $name leaves no input budget', ({ modelParams }) => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: undefined,
+ modelContextLength: 128_000,
+ modelParams,
+ }),
+ ).toBe(102_400);
+ });
+
+ it('falls back to 50K when the model context length is unknown', () => {
+ expect(
+ resolveCompactionThresholdTokens({
+ configuredThresholdTokens: undefined,
+ modelContextLength: undefined,
+ modelParams: { max_tokens: 32_768 },
+ }),
+ ).toBe(DEFAULT_CONTEXT_COMPACTION_THRESHOLD_TOKENS);
+ });
+});
diff --git a/packages/trueforge-ui/docs/server-types.temp.md b/packages/trueforge-ui/docs/server-types.temp.md
index 435b20dee..e5b8deade 100644
--- a/packages/trueforge-ui/docs/server-types.temp.md
+++ b/packages/trueforge-ui/docs/server-types.temp.md
@@ -186,16 +186,21 @@ export interface RuntimeConfig {
};
dynamicSubAgents?: { enabled?: boolean };
contextManagement?: {
- compaction?: {
- enabled?: boolean;
- compactionThresholdTokens?: number;
- };
+ compaction?: CompactionConfig;
largeToolResponse?: { enabled?: boolean };
};
generativeUi?: { enabled?: boolean };
askUserQuestions?: { enabled?: boolean };
}
+export interface CompactionConfig {
+ enabled?: boolean;
+ trigger?: {
+ type: 'input_tokens';
+ value: number;
+ };
+}
+
/** Agent Definition (gateway `TruefoundryGatewayApi.AgentSpec`) */
export interface AgentSpec {
model: Model;
diff --git a/packages/trueforge-ui/docs/server-types.temp.ts b/packages/trueforge-ui/docs/server-types.temp.ts
index 46650991e..502c98716 100644
--- a/packages/trueforge-ui/docs/server-types.temp.ts
+++ b/packages/trueforge-ui/docs/server-types.temp.ts
@@ -196,16 +196,21 @@ export interface RuntimeConfig {
};
dynamicSubAgents?: { enabled?: boolean };
contextManagement?: {
- compaction?: {
- enabled?: boolean;
- compactionThresholdTokens?: number;
- };
+ compaction?: CompactionConfig;
largeToolResponse?: { enabled?: boolean };
};
generativeUi?: { enabled?: boolean };
askUserQuestions?: { enabled?: boolean };
}
+export interface CompactionConfig {
+ enabled?: boolean;
+ trigger?: {
+ type: 'input_tokens';
+ value: number;
+ };
+}
+
/** Agent definition base. Hosts extend via `TSpec extends AgentSpec`. */
export interface AgentSpec {
model: Model;
diff --git a/packages/trueforge-ui/docs/server.md b/packages/trueforge-ui/docs/server.md
index 392688a92..7edf48f70 100644
--- a/packages/trueforge-ui/docs/server.md
+++ b/packages/trueforge-ui/docs/server.md
@@ -305,6 +305,14 @@ interface AgentSpec {
config?: RuntimeConfig;
}
+interface CompactionConfig {
+ enabled?: boolean;
+ trigger?: {
+ type: 'input_tokens';
+ value: number;
+ };
+}
+
interface Model {
name: string;
params?: ModelParams;
@@ -379,10 +387,7 @@ interface RuntimeConfig {
};
dynamicSubAgents?: { enabled?: boolean };
contextManagement?: {
- compaction?: {
- enabled?: boolean;
- compactionThresholdTokens?: number;
- };
+ compaction?: CompactionConfig;
largeToolResponse?: { enabled?: boolean };
};
generativeUi?: { enabled?: boolean };
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts
index a77533371..10b2a8200 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts
@@ -4,9 +4,7 @@ import type { AgentSpec } from '../../server/types.js';
export type HarnessSkillMount = TrueForgeApi.Skill;
export type HarnessMcpServerMount = TrueForgeApi.McpServer;
-export interface HarnessAgentSpec extends AgentSpec<TrueForgeApi.Model, HarnessSkillMount, HarnessMcpServerMount> {
- config?: TrueForgeApi.RuntimeConfig;
- instructions?: string;
- messages?: TrueForgeApi.InitialUserMessage[];
- responseFormat?: TrueForgeApi.ResponseFormat;
-}
+export interface HarnessAgentSpec
+ extends
+ AgentSpec<TrueForgeApi.Model, HarnessSkillMount, HarnessMcpServerMount, TrueForgeApi.RuntimeConfig>,
+ TrueForgeApi.AgentSpec {}
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index 26ec91bac..c6a154a3e 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -145,7 +145,7 @@ function createTurnResolver(deps: {
} = deps;
return new TurnResourceResolver({
llm: async name => {
- const { providerConfig, defaultModelParams } = await getModelDetails({
+ const { providerConfig, defaultModelParams, modelProperties } = await getModelDetails({
tenant_id: TENANT_ID,
name,
store: modelProviderStore,
@@ -157,6 +157,7 @@ function createTurnResolver(deps: {
signal,
}),
defaultModelParams,
+ modelProperties,
};
},
mcp: async name => {
diff --git a/packages/trueforge/src/db/migratePostgres.ts b/packages/trueforge/src/db/migratePostgres.ts
index cceb5b8bc..b7cec5da7 100644
--- a/packages/trueforge/src/db/migratePostgres.ts
+++ b/packages/trueforge/src/db/migratePostgres.ts
@@ -6,14 +6,8 @@ import { FileMigrationProvider, Migrator } from 'kysely/migration';
import type { Database } from './postgres/types';
-/**
- * Runs all pending Postgres migrations.
- *
- * This module lives at `src/db/` (bundled into `dist/main.js`) so the folder is
- * always `…/postgres/migrations` — source or production.
- */
-export async function migrateToLatest(db: Kysely<Database>): Promise<void> {
- const migrator = new Migrator({
+function createMigrator(db: Kysely<Database>): Migrator {
+ return new Migrator({
db,
provider: new FileMigrationProvider({
fs,
@@ -21,8 +15,15 @@ export async function migrateToLatest(db: Kysely<Database>): Promise<void> {
migrationFolder: path.join(import.meta.dirname, 'postgres', 'migrations'),
}),
});
+}
- const { error, results } = await migrator.migrateToLatest();
+async function runMigrations(input: { db: Kysely<Database>; targetMigrationName: string | undefined }): Promise<void> {
+ const migrator = createMigrator(input.db);
+
+ const { error, results } =
+ input.targetMigrationName === undefined
+ ? await migrator.migrateToLatest()
+ : await migrator.migrateTo(input.targetMigrationName);
results?.forEach(it => {
if (it.status === 'Success') {
@@ -39,3 +40,18 @@ export async function migrateToLatest(db: Kysely<Database>): Promise<void> {
throw new Error('failed to migrate', { cause: error });
}
}
+
+/**
+ * Runs all pending Postgres migrations.
+ *
+ * This module lives at `src/db/` (bundled into `dist/main.js`) so the folder is
+ * always `…/postgres/migrations` — source or production.
+ */
+export async function migrateToLatest(db: Kysely<Database>): Promise<void> {
+ await runMigrations({ db, targetMigrationName: undefined });
+}
+
+/** Runs Postgres migrations up to and including the named migration. */
+export async function migrateTo(db: Kysely<Database>, targetMigrationName: string): Promise<void> {
+ await runMigrations({ db, targetMigrationName });
+}
diff --git a/packages/trueforge/src/db/postgres/migrations/20260821_000001_agent_compaction.ts b/packages/trueforge/src/db/postgres/migrations/20260821_000001_agent_compaction.ts
new file mode 100644
index 000000000..69dbc00d5
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260821_000001_agent_compaction.ts
@@ -0,0 +1,61 @@
+import { sql, type Kysely } from 'kysely';
+
+/** Replace the legacy compaction token threshold with an input-token trigger. */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_set(
+ manifest #- '{config,context_management,compaction,compaction_threshold_tokens}',
+ '{config,context_management,compaction,trigger}',
+ coalesce(
+ manifest #> '{config,context_management,compaction,trigger}',
+ jsonb_build_object(
+ 'type', 'input_tokens',
+ 'value', (manifest #>> '{config,context_management,compaction,compaction_threshold_tokens}')::numeric
+ )
+ )
+ )
+ WHERE manifest #>> '{config,context_management,compaction,compaction_threshold_tokens}' IS NOT NULL
+ `.execute(db);
+ await sql`
+ UPDATE session
+ SET agent_spec = jsonb_set(
+ agent_spec #- '{config,context_management,compaction,compaction_threshold_tokens}',
+ '{config,context_management,compaction,trigger}',
+ coalesce(
+ agent_spec #> '{config,context_management,compaction,trigger}',
+ jsonb_build_object(
+ 'type', 'input_tokens',
+ 'value', (agent_spec #>> '{config,context_management,compaction,compaction_threshold_tokens}')::numeric
+ )
+ )
+ )
+ WHERE agent_spec #>> '{config,context_management,compaction,compaction_threshold_tokens}' IS NOT NULL
+ `.execute(db);
+}
+
+/** Restore the legacy token threshold for rollback compatibility. */
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_set(
+ manifest #- '{config,context_management,compaction,trigger}',
+ '{config,context_management,compaction,compaction_threshold_tokens}',
+ to_jsonb((manifest #>> '{config,context_management,compaction,trigger,value}')::numeric)
+ )
+ WHERE manifest #>> '{config,context_management,compaction,trigger,type}' = 'input_tokens'
+ AND manifest #>> '{config,context_management,compaction,trigger,value}' IS NOT NULL
+ `.execute(db);
+ await sql`
+ UPDATE session
+ SET agent_spec = jsonb_set(
+ agent_spec #- '{config,context_management,compaction,trigger}',
+ '{config,context_management,compaction,compaction_threshold_tokens}',
+ to_jsonb((agent_spec #>> '{config,context_management,compaction,trigger,value}')::numeric)
+ )
+ WHERE agent_spec #>> '{config,context_management,compaction,trigger,type}' = 'input_tokens'
+ AND agent_spec #>> '{config,context_management,compaction,trigger,value}' IS NOT NULL
+ `.execute(db);
+}
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260821_000001_agent_compaction.ts b/packages/trueforge/src/db/sqlite/migrations/20260821_000001_agent_compaction.ts
new file mode 100644
index 000000000..387561178
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260821_000001_agent_compaction.ts
@@ -0,0 +1,70 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Replace the legacy compaction token threshold with an input-token trigger.
+ * Mirrors db/postgres/migrations/20260821_000001_agent_compaction.ts.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await db.transaction().execute(async transaction => {
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_set(
+ jsonb_remove(manifest, '$.config.context_management.compaction.compaction_threshold_tokens'),
+ '$.config.context_management.compaction.trigger',
+ coalesce(
+ jsonb_extract(manifest, '$.config.context_management.compaction.trigger'),
+ jsonb(json_object(
+ 'type', 'input_tokens',
+ 'value', cast(
+ json_extract(manifest, '$.config.context_management.compaction.compaction_threshold_tokens') AS INTEGER
+ )
+ ))
+ )
+ )
+ WHERE json_extract(manifest, '$.config.context_management.compaction.compaction_threshold_tokens') IS NOT NULL
+ `.execute(transaction);
+ await sql`
+ UPDATE session
+ SET agent_spec = jsonb_set(
+ jsonb_remove(agent_spec, '$.config.context_management.compaction.compaction_threshold_tokens'),
+ '$.config.context_management.compaction.trigger',
+ coalesce(
+ jsonb_extract(agent_spec, '$.config.context_management.compaction.trigger'),
+ jsonb(json_object(
+ 'type', 'input_tokens',
+ 'value', cast(
+ json_extract(agent_spec, '$.config.context_management.compaction.compaction_threshold_tokens') AS INTEGER
+ )
+ ))
+ )
+ )
+ WHERE json_extract(agent_spec, '$.config.context_management.compaction.compaction_threshold_tokens') IS NOT NULL
+ `.execute(transaction);
+ });
+}
+
+/** Restore the legacy token threshold for rollback compatibility. */
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await db.transaction().execute(async transaction => {
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_set(
+ jsonb_remove(manifest, '$.config.context_management.compaction.trigger'),
+ '$.config.context_management.compaction.compaction_threshold_tokens',
+ cast(json_extract(manifest, '$.config.context_management.compaction.trigger.value') AS INTEGER)
+ )
+ WHERE json_extract(manifest, '$.config.context_management.compaction.trigger.type') = 'input_tokens'
+ AND json_extract(manifest, '$.config.context_management.compaction.trigger.value') IS NOT NULL
+ `.execute(transaction);
+ await sql`
+ UPDATE session
+ SET agent_spec = jsonb_set(
+ jsonb_remove(agent_spec, '$.config.context_management.compaction.trigger'),
+ '$.config.context_management.compaction.compaction_threshold_tokens',
+ cast(json_extract(agent_spec, '$.config.context_management.compaction.trigger.value') AS INTEGER)
+ )
+ WHERE json_extract(agent_spec, '$.config.context_management.compaction.trigger.type') = 'input_tokens'
+ AND json_extract(agent_spec, '$.config.context_management.compaction.trigger.value') IS NOT NULL
+ `.execute(transaction);
+ });
+}
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index ee97d7246..e053e6694 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -5,6 +5,7 @@ import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';
import {
Sandbox,
SkillMounter,
+ type AgentDefinition,
type AgentTracing,
type GitSkill,
type ModelParams,
@@ -59,6 +60,7 @@ export async function getModelDetails({
}): Promise<{
providerConfig: VercelAIProviderConfig;
defaultModelParams: ModelParams;
+ modelProperties: AgentDefinition['modelProperties'];
}> {
const parsed = parseModelFqn(name);
if (parsed === undefined) {
@@ -92,6 +94,7 @@ export async function getModelDetails({
headers: {},
},
defaultModelParams: model.properties.max_output_tokens ? { max_tokens: model.properties.max_output_tokens } : {},
+ modelProperties: { contextLength: model.properties.context_length },
};
}
diff --git a/packages/trueforge/tests/db/postgres/migrations/20260821_000001_agent_compaction.test.ts b/packages/trueforge/tests/db/postgres/migrations/20260821_000001_agent_compaction.test.ts
new file mode 100644
index 000000000..b94ba5088
--- /dev/null
+++ b/packages/trueforge/tests/db/postgres/migrations/20260821_000001_agent_compaction.test.ts
@@ -0,0 +1,111 @@
+import { sql } from 'kysely';
+
+import { down, up } from '../../../../src/db/postgres/migrations/20260821_000001_agent_compaction';
+import { createPostgresTestDatabase, type PostgresTestDatabase } from '../testDatabase';
+
+const describePg = process.env['PG_STORE_TESTS_ENABLED'] === '1' ? describe : describe.skip;
+const LARGE_THRESHOLD = 3_000_000_000;
+const PREVIOUS_MIGRATION = '20260818_000001_mcp_pending_auth_return_to';
+
+describePg('Postgres agent compaction migration', () => {
+ let env: PostgresTestDatabase | undefined;
+
+ beforeAll(async () => {
+ env = await createPostgresTestDatabase(PREVIOUS_MIGRATION);
+ if (env === undefined) {
+ throw new Error('Postgres test environment unavailable despite globalSetup probe');
+ }
+ }, 120_000);
+
+ afterAll(async () => {
+ await env?.teardown();
+ });
+
+ it('preserves large thresholds for named and inline Agent Specs during upgrade and rollback', async () => {
+ if (env === undefined) {
+ throw new Error('Postgres test environment not initialized');
+ }
+
+ const legacySpecObject = {
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: { enabled: false, compaction_threshold_tokens: LARGE_THRESHOLD },
+ },
+ },
+ };
+ const legacySpec = JSON.stringify(legacySpecObject);
+
+ await sql`
+ INSERT INTO agent (id, tenant_id, name, manifest, created_at, updated_at)
+ VALUES ('legacy-agent', 'tenant-1', 'legacy-agent', ${legacySpec}::jsonb, now(), now())
+ `.execute(env.db);
+ await sql`
+ INSERT INTO session (
+ tenant_id,
+ session_id,
+ created_by,
+ agent_id,
+ agent_name,
+ agent_spec,
+ title,
+ last_turn_id,
+ custom,
+ last_activity_timestamp_ms,
+ created_at,
+ updated_at
+ )
+ VALUES (
+ 'tenant-1',
+ 'legacy-session',
+ 'user-1',
+ NULL,
+ NULL,
+ ${legacySpec}::jsonb,
+ NULL,
+ NULL,
+ NULL,
+ 0,
+ now(),
+ now()
+ )
+ `.execute(env.db);
+
+ await env.db.transaction().execute(async transaction => {
+ await up(transaction);
+ });
+
+ const migratedAgent = await sql<{ manifest: unknown }>`
+ SELECT manifest FROM agent WHERE id = 'legacy-agent'
+ `.execute(env.db);
+ const migratedSession = await sql<{ agent_spec: unknown }>`
+ SELECT agent_spec FROM session WHERE session_id = 'legacy-session'
+ `.execute(env.db);
+ const expectedMigratedSpec = {
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: {
+ enabled: false,
+ trigger: { type: 'input_tokens', value: LARGE_THRESHOLD },
+ },
+ },
+ },
+ };
+ expect(migratedAgent.rows[0]?.manifest).toEqual(expectedMigratedSpec);
+ expect(migratedSession.rows[0]?.agent_spec).toEqual(expectedMigratedSpec);
+
+ await env.db.transaction().execute(async transaction => {
+ await down(transaction);
+ });
+
+ const rolledBackAgent = await sql<{ manifest: unknown }>`
+ SELECT manifest FROM agent WHERE id = 'legacy-agent'
+ `.execute(env.db);
+ const rolledBackSession = await sql<{ agent_spec: unknown }>`
+ SELECT agent_spec FROM session WHERE session_id = 'legacy-session'
+ `.execute(env.db);
+ expect(rolledBackAgent.rows[0]?.manifest).toEqual(legacySpecObject);
+ expect(rolledBackSession.rows[0]?.agent_spec).toEqual(legacySpecObject);
+ });
+});
diff --git a/packages/trueforge/tests/db/postgres/testDatabase.ts b/packages/trueforge/tests/db/postgres/testDatabase.ts
index 624b3d21c..4ea4b41f7 100644
--- a/packages/trueforge/tests/db/postgres/testDatabase.ts
+++ b/packages/trueforge/tests/db/postgres/testDatabase.ts
@@ -6,7 +6,7 @@ import type { Kysely } from 'kysely';
import { Pool } from 'pg';
import { ulid } from 'ulid';
-import { migrateToLatest } from '../../../src/db/migratePostgres';
+import { migrateTo, migrateToLatest } from '../../../src/db/migratePostgres';
import { createDb } from '../../../src/db/postgres/client';
import type { Database } from '../../../src/db/postgres/types';
@@ -51,7 +51,9 @@ async function dropDatabase(adminUrl: string, databaseName: string): Promise<voi
}
}
-export async function createPostgresTestDatabase(): Promise<PostgresTestDatabase | undefined> {
+export async function createPostgresTestDatabase(
+ targetMigrationName?: string,
+): Promise<PostgresTestDatabase | undefined> {
const adminUrl = resolveAdminUrl();
if (adminUrl === undefined) {
return undefined;
@@ -75,7 +77,11 @@ export async function createPostgresTestDatabase(): Promise<PostgresTestDatabase
idleInTransactionSessionTimeoutMs: 60_000,
});
try {
- await migrateToLatest(db);
+ if (targetMigrationName === undefined) {
+ await migrateToLatest(db);
+ } else {
+ await migrateTo(db, targetMigrationName);
+ }
} catch (error) {
await db.destroy();
await dropDatabase(adminUrl, databaseName);
diff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.ts
index bafaa62da..185db7fc1 100644
--- a/packages/trueforge/tests/unit/apis/agents.test.ts
+++ b/packages/trueforge/tests/unit/apis/agents.test.ts
@@ -23,6 +23,14 @@ const modelProvider = {
const manifest = {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'Be helpful.',
+ config: {
+ context_management: {
+ compaction: {
+ enabled: true,
+ trigger: { type: 'input_tokens', value: 80_000 },
+ },
+ },
+ },
};
const writeBody = {
@@ -40,7 +48,15 @@ const updateBody = {
type WireAgent = {
id: string;
name: string;
- manifest: { model: { name: string }; instructions?: string };
+ manifest: {
+ model: { name: string };
+ instructions?: string;
+ config?: {
+ context_management?: {
+ compaction?: { enabled: boolean; trigger?: { type: 'input_tokens'; value: number } };
+ };
+ };
+ };
};
function jsonInit(method: string, body: unknown): RequestInit {
@@ -79,6 +95,14 @@ describe('agents router', () => {
manifest: {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'Be helpful.',
+ config: {
+ context_management: {
+ compaction: {
+ enabled: true,
+ trigger: { type: 'input_tokens', value: 80_000 },
+ },
+ },
+ },
},
});
diff --git a/packages/trueforge/tests/unit/db/sqlite/migrations/20260821_000001_agent_compaction.test.ts b/packages/trueforge/tests/unit/db/sqlite/migrations/20260821_000001_agent_compaction.test.ts
new file mode 100644
index 000000000..e8468b136
--- /dev/null
+++ b/packages/trueforge/tests/unit/db/sqlite/migrations/20260821_000001_agent_compaction.test.ts
@@ -0,0 +1,94 @@
+import { sql } from 'kysely';
+import { createSqliteDb } from '../../../../../src/db/sqlite/client';
+import { down, up } from '../../../../../src/db/sqlite/migrations/20260821_000001_agent_compaction';
+
+describe('SQLite agent compaction migration', () => {
+ it('upgrades named and inline Agent Specs to the trigger shape and rolls them back', async () => {
+ const db = createSqliteDb(':memory:');
+ try {
+ await sql`CREATE TABLE agent (manifest BLOB NOT NULL) STRICT`.execute(db);
+ await sql`CREATE TABLE session (agent_spec BLOB) STRICT`.execute(db);
+
+ const namedSpec = JSON.stringify({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: { enabled: false, compaction_threshold_tokens: 80_000 },
+ large_tool_response: { enabled: true },
+ },
+ },
+ });
+ const inlineSpec = JSON.stringify({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: { enabled: true, compaction_threshold_tokens: 60_000 },
+ large_tool_response: { enabled: false },
+ },
+ },
+ });
+ await sql`INSERT INTO agent (manifest) VALUES (jsonb(${namedSpec}))`.execute(db);
+ await sql`INSERT INTO session (agent_spec) VALUES (jsonb(${inlineSpec}))`.execute(db);
+
+ await up(db);
+
+ const migratedAgent = await sql<{ manifest: unknown }>`SELECT json(manifest) AS manifest FROM agent`.execute(db);
+ const migratedSession = await sql<{ agent_spec: unknown }>`
+ SELECT json(agent_spec) AS agent_spec FROM session
+ `.execute(db);
+ expect(migratedAgent.rows[0]?.manifest).toEqual({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: {
+ enabled: false,
+ trigger: { type: 'input_tokens', value: 80_000 },
+ },
+ large_tool_response: { enabled: true },
+ },
+ },
+ });
+ expect(migratedSession.rows[0]?.agent_spec).toEqual({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ compaction: {
+ enabled: true,
+ trigger: { type: 'input_tokens', value: 60_000 },
+ },
+ large_tool_response: { enabled: false },
+ },
+ },
+ });
+
+ await down(db);
+
+ const rolledBackAgent = await sql<{ manifest: unknown }>`SELECT json(manifest) AS manifest FROM agent`.execute(
+ db,
+ );
+ const rolledBackSession = await sql<{ agent_spec: unknown }>`
+ SELECT json(agent_spec) AS agent_spec FROM session
+ `.execute(db);
+ expect(rolledBackAgent.rows[0]?.manifest).toEqual({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ large_tool_response: { enabled: true },
+ compaction: { enabled: false, compaction_threshold_tokens: 80_000 },
+ },
+ },
+ });
+ expect(rolledBackSession.rows[0]?.agent_spec).toEqual({
+ model: { name: 'provider/model' },
+ config: {
+ context_management: {
+ large_tool_response: { enabled: false },
+ compaction: { enabled: true, compaction_threshold_tokens: 60_000 },
+ },
+ },
+ });
+ } finally {
+ await db.destroy();
+ }
+ });
+});
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index 4822a13f0..b3d763f79 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -77,6 +77,7 @@ describe('validateAgentSpec', () => {
name: 'test-provider/test-model',
},
defaultModelParams: { max_tokens: 4096 },
+ modelProperties: { contextLength: 128000 },
});
});