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.mdnew file mode 100644index 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.pyindex 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.mdxindex 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.mdxindex 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.```mermaidflowchart 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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/tokenizerconst 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.tsindex 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.tsindex 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.tsindex 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>): boolereturn 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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.tsindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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<PostgresTestDatabaseidleInTransactionSessionTimeoutMs: 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 },});});