Constrain agent names to hyphen-only 2–64 and migrate ./_ names

[bhaveshpatel640]

Summary

Align TrueForge agent names to hyphen-only 2–64 char and migration to enforce hyphen-only naming convention

Closes AGE-2065

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, .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
Irreversible data migration renames live agent identifiers and denormalized references; API clients can no longer create agents with . or _ in names.

Overview
Introduces a dedicated AgentName type (OpenAPI, SDK, and Zod) for agent registry identifiers: 2–64 lowercase characters, hyphens only between the leading letter and trailing alphanumeric. Agent create/list, schedules’ agent_name, and session name refs now validate against this stricter rule instead of generic ResourceName (which still allows . and _ for other resources like schedule names).

Create agent requests with dotted or underscored names are rejected; reserved names (tfg, trueforge) behavior is unchanged.

A one-way Postgres/SQLite migration rewrites existing agents whose names contain . or _ by hyphenating and appending a random 4-hex suffix (with truncation to fit 64 chars), and updates denormalized session.agent_name and schedule.agent_name to match. Original names are not preserved.

Unit tests cover AgentNameSchema, rename planning, and API rejection of invalid agent names.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: d9217da

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

This PR includes changesets to release 1 package

Name	Type
@truefoundry/trueforge	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 dd2b040. Configure here.}

[cursor]

Remote TrueFoundry agents stay unrenamed

Medium Severity

The migration rewrites only local agent.name (and denormalized session/schedule copies). In TrueFoundry mode, putRemoteAgent is keyed by name and does not receive external_id, so the next agent update PUTs the new local name and can create a new ServiceFoundry agent, orphan the old remote, and drop MCP grants bound to it.

Additional Locations (1)

• packages/trueforge/src/db/sqlite/migrations/20260910_000001_agent_name_hyphen_only.ts#L19-L36

 

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