feat: Write paused instead of done on HITL

[sr07asthana]

Summary

Closes #

Changes

How was this tested?

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, python/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 API/SDK shape change to turn lifecycle and store CAS rules; clients that relied on done + required_actions must switch to paused + turn.update.

Overview
Human-in-the-loop turns now end in paused with a turn.update event, not done carrying pending approvals. TurnHandle maps orchestrator required_actions to action_required_on_events (event ids only) and persists via the same updateTurnState path, emitting turn.update instead of turn.done.

The public turn model is tightened: TurnStateDone drops required_actions; TurnStatePaused is a first-class TurnState (OpenAPI, Zod, TS/Python SDK). Live updates reuse TurnStatePaused / TurnStateRunning instead of separate TurnUpdateState* types, and ActionRequiredEvent is removed from the spec.

Session store semantics change with pause: the first running → non-running write wins (so a paused turn blocks a follow-up done until resume/freeze flows); session cost/duration metrics are folded only for terminal states, not on pause. Postgres/SQLite and in-memory stores align on that behavior, with new contract and stream tests for HITL approval gating.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 095ddcc

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-sdk	Patch
@truefoundry/trueforge	Patch
@truefoundry/trueforge-core	Patch
@truefoundry/trueforge-ui	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

[cursor]

Stale Bugbot comment from a previous run.

[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 095ddcc. Configure here.}

[cursor]

SDK pause types break UI adapter

High Severity

Regenerated TurnState now includes paused, and TurnStateDone no longer has requiredActions. The in-repo UI adapter still treats HITL as done plus requiredActions and does not map paused, so trueforge-ui typecheck fails and paused turns cannot be shown in chat.

Additional Locations (1)

• packages/trueforge-sdk/src/api/types/TurnStateDone.ts#L4-L12

 

^{Triggered by project rule: TrueForge review rules}

^{Reviewed by Cursor Bugbot for commit 095ddcc. Configure here.}