Tighten NameSchema to hyphen-only 2–64 and migrate legacy ./_ names

[bhaveshpatel640]

Summary

Align TrueForge shared NameSchema (ResourceName) with ServiceFoundry agent-identity / RemoteAgentV2: hyphen-only, 2–64 (^[a-z][a-z0-9-]{0,62}[a-z0-9]$).

One schema for local resource names (agents, skills, MCP servers, models, schedules). Postgres + SQLite migration rewrites legacy local names that used . / _.

Closes AGE-2065

Why

• TF agent names must match SVC PUT /internal/tfg/agents / agent-identity (source=trueforge).
• Older TF ResourceName allowed . / _; that breaks SVC sync and diverges from RemoteAgentV2.
• Prefer one shared NameSchema over a separate AgentNameSchema so standalone create/list/update stay consistent after migrate.

Changes

Schema

• Tighten NameSchema in packages/trueforge/src/schemas/common.ts to hyphen-only 2–64.
• OpenAPI name remains ResourceName (CI regenerates OpenAPI + SDK; no hand-edits).
• Document TFY vs standalone vs migration behavior on NameSchema.

API / validation impact

• Create/update APIs that use NameSchema reject names with . or _ (e.g. my.agent, my_agent).
• Reserved agent names (tfg, trueforge) unchanged.
• AgentSpec refs (model / skills / MCP) stay plain strings — FQNs and long SVC names still allowed in manifests.

TrueFoundry mode

• Agents: created/synced under NameSchema (must satisfy SVC identity).
• Skills / MCP / models: fetched from SVC; not NameSchema-checked on those paths (FQNs / longer SVC MCP names OK).
• Schedules: still local; use NameSchema.

Standalone mode

• Agents, skills, MCP, models, schedules are created locally under the same NameSchema.

Migration (20260911_000001_name_hyphen_only)

• Shared planner: planHyphenOnlyRenames.ts
• Shared apply: applyNameHyphenOnlyMigration.ts
• Wired for Postgres and SQLite
• Rewrites only strings matching legacy NameSchema that fail the new rule (contain . / _)
• Replace . / _ → -, always append -<4 hex>; truncate to ≤ 64
• Leaves alone: already hyphen-only names, FQNs, other non-matching strings
• Updates:
  • agent.name + denorm session.agent_name / schedule.agent_name
  • skill.name
  • mcp_server.name (+ manifest.name)
  • model_provider.name (+ nested models[].name, custom manifest.name)
  • schedule.name
  • AgentSpec refs on agent/session manifests
• Irreversible (down throws); originals not retained; no occupancy / collision check on suffix

Tests

• nameSchema.test.ts — accept/reject matrix
• planHyphenOnlyRenames.test.ts — rename + FQN skip + AgentSpec rewrite maps
• agents.test.ts — API rejects my.agent / my_agent
• trueFoundryNaming.test.ts — TFY runtime: agent name still NameSchema; skill FQN / long MCP / model FQN work on create/update, stores, mappers; OpenAPI MCP schemas may still be stricter than runtime (documented)

Release

• Patch changeset for @truefoundry/trueforge
• OpenAPI / @truefoundry/trueforge-sdk regenerate in CI after merge (do not hand-edit)

Out of scope / known skew

• SVC TrueFoundryAgentManifest (3–32, no --) is not the TF ensure path; TF aligns to agent-identity (2–64).
• TFY MCP list/get can return names longer than 64 / outside NameSchema; some OpenAPI MCP types still declare ResourceName — runtime path does not re-parse those schemas today.
• Clients hardcoding old . / _ local names must switch to post-migration names.

How was this tested?

• Unit: nameSchema, planHyphenOnlyRenames, trueFoundryNaming, agents API reject cases
• Full package / root pnpm test (as needed before merge)
• pnpm smoke / migrate against a DB that still has legacy . / _ names (recommended)
• Manual: create agent with hyphen name; reject dotted name; TFY agent with skill FQN + model FQN in manifest

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

High Risk
Irreversible multi-table data migration renames user resources and embedded references; API validation breaks clients still using ./_ local names.

Overview
ResourceName / NameSchema now allows only lowercase letters, digits, and hyphens (2–64 chars), aligned with ServiceFoundry agent identity. Dotted and underscored local names are rejected on create/update; OpenAPI ResourceName pattern matches.

A one-time, irreversible Postgres/SQLite migration renames existing local rows whose names still used . or _: providers (including nested model names), skills, MCP servers, schedules, and agents, then fixes session / schedule agent_name and model / MCP / skill refs inside agent and session JSON. Renames hyphenate, append a short random suffix, and skip FQNs and names already compliant.

Tests cover schema rules, rename planning, SQLite migration integrity, agent API rejection, and TrueFoundry mode where agent names stay strict while manifest refs can remain FQNs or long SVC names.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: ab5cf4c

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 2 potential issues.

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

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

[heerambavi1998]

can we do this after 286 check.

[cursor]

Current version of PR was reviewed by /review-bugbot with additional instructions on Sep 11, 16:31 GMT+5:30. It flagged 1 finding.

Show 1 finding

1. Provider rename map without row update

packages/trueforge/src/db/applyNameHyphenOnlyMigration.ts:280 · Medium Severity

In the model-provider loop, a provider rename is appended to providerRenames before the manifest is parsed, but an unparseable manifest triggers continue and skips the UPDATE. Step 5 then rewrites agent and session specs to the planned new provider name while the model_provider row still holds the legacy name.

^{Bugbot on commit ab5cf4c is skipped.}