feat: add agent compaction triggers

[vivekascoder]

Summary

Adds configurable context compaction triggers while preserving backward compatibility with legacy compaction settings.

Closes #399

Changes

• Adds context_management.compaction.trigger with input_tokens support.
• Defaults to 80% of model context length, or 50K tokens when unknown.
• Migrates legacy persisted compaction thresholds in PostgreSQL and SQLite.
• Preserves compatibility with legacy API requests and resolver implementations.
• Updates tests, documentation, and package changesets.

How was this tested?

• pnpm build
• pnpm test
• pnpm test:store:local
• pnpm typecheck
• pnpm lint:ci
• pnpm format:check
• pnpm --filter @truefoundry/trueforge-core pack:dry

Checklist

• I have read the contributing guidelines
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• No hand-edits to generated code (packages/trueforge-sdk, .github/fern/openapi/openapi.json, docs/openapi.json) — fork PRs omit SDK regen; maintainers regenerate after merge
• Docs / .env.example updated if configuration or behavior changed

---

Note

Medium Risk
This is a breaking Agent Spec change plus JSON rewrites of stored agent/session configs. Wrong migration or default thresholds can compact too early/late on long runs.

Overview
Replaces the flat compaction_threshold_tokens setting with context_management.compaction.trigger (type: input_tokens, optional value). New API writes that still send the old field are rejected.

When trigger is omitted, compaction now fires at 80% of the resolved model context length, capped by remaining input budget after max_completion_tokens/max_tokens, and falls back to 50k if context length is unknown. Model contextLength is threaded from catalog properties through getModelDetails into AgentDefinition.

Postgres and SQLite migrations rewrite persisted agent manifests and session specs from the legacy threshold to the new trigger shape (with rollback). Docs, UI types, and the benchmark spec are updated to match.

^{Reviewed by Cursor Bugbot for commit 3f81f64. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 3f81f64

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@truefoundry/trueforge-core	Minor
@truefoundry/trueforge	Minor
@truefoundry/trueforge-ui	Minor
frontend	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[debajyoti-truefoundry]

@sr07asthana to do the first-pass review.

[vivekascoder]

@debajyoti-truefoundry removed the backward compatibility.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3f81f64. Configure here.}

[cursor]

Optional contextLength on internal contracts

Low Severity

contextLength is declared with ? on AgentDefinition and the TurnResourceResolver llm result, so callers can omit the field. The trueforge-core optional-properties rule requires internal contracts to use an explicit required number | undefined (as getModelDetails already does) rather than an optional property.

Additional Locations (1)

• packages/trueforge-core/src/agent-session/TurnResourceResolver.ts#L63-L64

 

^{Triggered by project rule: @truefoundry/trueforge-core review rules}

^{Reviewed by Cursor Bugbot for commit 3f81f64. Configure here.}

[vivekascoder]

Top-level public package surfaces (core, agent-session, and other exported entrypoints) MAY use optional (?) properties for caller ergonomics.

is it still valid?

[vivekascoder]

@debajyoti-truefoundry anything here?