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

.changeset/20260901165900-agent-name-hyphen-only.md

@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge': patch
+---
+
+Constrain agent names to hyphen-only 2–64 and rename existing "."/"_" agent names.

.github/fern/openapi/openapi.json

@@ -35,7 +35,7 @@
             "$ref": "#/components/schemas/AgentSpec"
           },
           "name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           }
         },
         "required": [
@@ -141,6 +141,12 @@
         ],
         "type": "object"
       },
+      "AgentName": {
+        "maxLength": 64,
+        "minLength": 2,
+        "pattern": "^[a-z][a-z0-9-]{0,62}[a-z0-9]$",
+        "type": "string"
+      },
       "AgentParent": {
         "properties": {
           "thread_id": {
@@ -959,7 +965,7 @@
             "$ref": "#/components/schemas/AgentSpec"
           },
           "name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           }
         },
         "required": [
@@ -996,7 +1002,7 @@
         "additionalProperties": false,
         "properties": {
           "agent_name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           },
           "manifest": {
             "$ref": "#/components/schemas/ScheduleManifest"
@@ -3012,7 +3018,7 @@
         "additionalProperties": false,
         "properties": {
           "agent_name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           },
           "created_at": {
             "format": "date-time",
@@ -3221,7 +3227,7 @@
         "additionalProperties": false,
         "properties": {
           "name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           }
         },
         "required": [
@@ -5785,7 +5791,7 @@
             "name": "agent_name",
             "required": false,
             "schema": {
-              "$ref": "#/components/schemas/ResourceName"
+              "$ref": "#/components/schemas/AgentName"
             }
           }
         ],

docs/openapi.json

@@ -35,7 +35,7 @@
             "$ref": "#/components/schemas/AgentSpec"
           },
           "name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           }
         },
         "required": [
@@ -141,6 +141,12 @@
         ],
         "type": "object"
       },
+      "AgentName": {
+        "maxLength": 64,
+        "minLength": 2,
+        "pattern": "^[a-z][a-z0-9-]{0,62}[a-z0-9]$",
+        "type": "string"
+      },
       "AgentParent": {
         "properties": {
           "thread_id": {
@@ -959,7 +965,7 @@
             "$ref": "#/components/schemas/AgentSpec"
           },
           "name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           }
         },
         "required": [
@@ -996,7 +1002,7 @@
         "additionalProperties": false,
         "properties": {
           "agent_name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           },
           "manifest": {
             "$ref": "#/components/schemas/ScheduleManifest"
@@ -3012,7 +3018,7 @@
         "additionalProperties": false,
         "properties": {
           "agent_name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           },
           "created_at": {
             "format": "date-time",
@@ -3221,7 +3227,7 @@
         "additionalProperties": false,
         "properties": {
           "name": {
-            "$ref": "#/components/schemas/ResourceName"
+            "$ref": "#/components/schemas/AgentName"
           }
         },
         "required": [
@@ -5785,7 +5791,7 @@
             "name": "agent_name",
             "required": false,
             "schema": {
-              "$ref": "#/components/schemas/ResourceName"
+              "$ref": "#/components/schemas/AgentName"
             }
           }
         ],

packages/trueforge-sdk/src/api/resources/agents/client/requests/CreateAgentRequest.ts

@@ -15,5 +15,5 @@ import type * as TrueForge from "../../../../index.js";
  */
 export interface CreateAgentRequest {
     manifest: TrueForge.AgentSpec;
-    name: TrueForge.ResourceName;
+    name: TrueForge.AgentName;
 }

packages/trueforge-sdk/src/api/resources/schedules/client/requests/CreateScheduleRequest.ts

@@ -14,7 +14,7 @@ import type * as TrueForge from "../../../../index.js";
  *     }
  */
 export interface CreateScheduleRequest {
-    agentName: TrueForge.ResourceName;
+    agentName: TrueForge.AgentName;
     manifest: TrueForge.ScheduleManifest;
     name: TrueForge.ResourceName;
 }

packages/trueforge-sdk/src/api/resources/schedules/client/requests/ListSchedulesRequest.ts

@@ -7,5 +7,5 @@ import type * as TrueForge from "../../../../index.js";
  *     {}
  */
 export interface ListSchedulesRequest {
-    agentName?: TrueForge.ResourceName;
+    agentName?: TrueForge.AgentName;
 }

packages/trueforge-sdk/src/api/types/Agent.ts

@@ -6,5 +6,5 @@ export interface Agent {
     /** Immutable server-generated agent identifier. */
     id: string;
     manifest: TrueForge.AgentSpec;
-    name: TrueForge.ResourceName;
+    name: TrueForge.AgentName;
 }

packages/trueforge-sdk/src/api/types/AgentName.ts

@@ -0,0 +1,3 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export type AgentName = string;

packages/trueforge-sdk/src/api/types/Schedule.ts

@@ -3,7 +3,7 @@
 import type * as TrueForge from "../index.js";
 
 export interface Schedule {
-    agentName: TrueForge.ResourceName;
+    agentName: TrueForge.AgentName;
     createdAt: Date;
     createdBy: string;
     id: string;

packages/trueforge-sdk/src/api/types/SessionAgentNameRef.ts

@@ -3,5 +3,5 @@
 import type * as TrueForge from "../index.js";
 
 export interface SessionAgentNameRef {
-    name: TrueForge.ResourceName;
+    name: TrueForge.AgentName;
 }

packages/trueforge-sdk/src/api/types/index.ts

@@ -4,6 +4,7 @@ export * from "./AgentCodeSnippet.js";
 export * from "./AgentCodeSnippetSampleCode.js";
 export * from "./AgentCodeSnippets.js";
 export * from "./AgentInfo.js";
+export * from "./AgentName.js";
 export * from "./AgentParent.js";
 export * from "./AgentSpec.js";
 export * from "./AlibabaModelProvider.js";

packages/trueforge-sdk/src/serialization/resources/agents/client/requests/CreateAgentRequest.ts

@@ -3,20 +3,20 @@
 import type * as TrueForge from "../../../../../api/index.js";
 import * as core from "../../../../../core/index.js";
 import type * as serializers from "../../../../index.js";
+import { AgentName } from "../../../../types/AgentName.js";
 import { AgentSpec } from "../../../../types/AgentSpec.js";
-import { ResourceName } from "../../../../types/ResourceName.js";
 
 export const CreateAgentRequest: core.serialization.Schema<
     serializers.CreateAgentRequest.Raw,
     TrueForge.CreateAgentRequest
 > = core.serialization.object({
     manifest: AgentSpec,
-    name: ResourceName,
+    name: AgentName,
 });
 
 export declare namespace CreateAgentRequest {
     export interface Raw {
         manifest: AgentSpec.Raw;
-        name: ResourceName.Raw;
+        name: AgentName.Raw;
     }
 }

packages/trueforge-sdk/src/serialization/resources/schedules/client/requests/CreateScheduleRequest.ts

@@ -3,21 +3,22 @@
 import type * as TrueForge from "../../../../../api/index.js";
 import * as core from "../../../../../core/index.js";
 import type * as serializers from "../../../../index.js";
+import { AgentName } from "../../../../types/AgentName.js";
 import { ResourceName } from "../../../../types/ResourceName.js";
 import { ScheduleManifest } from "../../../../types/ScheduleManifest.js";
 
 export const CreateScheduleRequest: core.serialization.Schema<
     serializers.CreateScheduleRequest.Raw,
     TrueForge.CreateScheduleRequest
 > = core.serialization.object({
-    agentName: core.serialization.property("agent_name", ResourceName),
+    agentName: core.serialization.property("agent_name", AgentName),
     manifest: ScheduleManifest,
     name: ResourceName,
 });
 
 export declare namespace CreateScheduleRequest {
     export interface Raw {
-        agent_name: ResourceName.Raw;
+        agent_name: AgentName.Raw;
         manifest: ScheduleManifest.Raw;
         name: ResourceName.Raw;
     }

packages/trueforge-sdk/src/serialization/types/Agent.ts

@@ -3,21 +3,21 @@
 import type * as TrueForge from "../../api/index.js";
 import * as core from "../../core/index.js";
 import type * as serializers from "../index.js";
+import { AgentName } from "./AgentName.js";
 import { AgentSpec } from "./AgentSpec.js";
-import { ResourceName } from "./ResourceName.js";
 
 export const Agent: core.serialization.ObjectSchema<serializers.Agent.Raw, TrueForge.Agent> = core.serialization.object(
     {
         id: core.serialization.string(),
         manifest: AgentSpec,
-        name: ResourceName,
+        name: AgentName,
     },
 );
 
 export declare namespace Agent {
     export interface Raw {
         id: string;
         manifest: AgentSpec.Raw;
-        name: ResourceName.Raw;
+        name: AgentName.Raw;
     }
 }

packages/trueforge-sdk/src/serialization/types/AgentName.ts

@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const AgentName: core.serialization.Schema<serializers.AgentName.Raw, TrueForge.AgentName> =
+    core.serialization.string();
+
+export declare namespace AgentName {
+    export type Raw = string;
+}

packages/trueforge-sdk/src/serialization/types/Schedule.ts

@@ -3,12 +3,13 @@
 import type * as TrueForge from "../../api/index.js";
 import * as core from "../../core/index.js";
 import type * as serializers from "../index.js";
+import { AgentName } from "./AgentName.js";
 import { ResourceName } from "./ResourceName.js";
 import { ScheduleManifest } from "./ScheduleManifest.js";
 
 export const Schedule: core.serialization.ObjectSchema<serializers.Schedule.Raw, TrueForge.Schedule> =
     core.serialization.object({
-        agentName: core.serialization.property("agent_name", ResourceName),
+        agentName: core.serialization.property("agent_name", AgentName),
         createdAt: core.serialization.property("created_at", core.serialization.date()),
         createdBy: core.serialization.property("created_by", core.serialization.string()),
         id: core.serialization.string(),
@@ -19,7 +20,7 @@ export const Schedule: core.serialization.ObjectSchema<serializers.Schedule.Raw,
 
 export declare namespace Schedule {
     export interface Raw {
-        agent_name: ResourceName.Raw;
+        agent_name: AgentName.Raw;
         created_at: string;
         created_by: string;
         id: string;

packages/trueforge-sdk/src/serialization/types/SessionAgentNameRef.ts

@@ -3,17 +3,17 @@
 import type * as TrueForge from "../../api/index.js";
 import * as core from "../../core/index.js";
 import type * as serializers from "../index.js";
-import { ResourceName } from "./ResourceName.js";
+import { AgentName } from "./AgentName.js";
 
 export const SessionAgentNameRef: core.serialization.ObjectSchema<
     serializers.SessionAgentNameRef.Raw,
     TrueForge.SessionAgentNameRef
 > = core.serialization.object({
-    name: ResourceName,
+    name: AgentName,
 });
 
 export declare namespace SessionAgentNameRef {
     export interface Raw {
-        name: ResourceName.Raw;
+        name: AgentName.Raw;
     }
 }

packages/trueforge-sdk/src/serialization/types/index.ts

@@ -4,6 +4,7 @@ export * from "./AgentCodeSnippet.js";
 export * from "./AgentCodeSnippetSampleCode.js";
 export * from "./AgentCodeSnippets.js";
 export * from "./AgentInfo.js";
+export * from "./AgentName.js";
 export * from "./AgentParent.js";
 export * from "./AgentSpec.js";
 export * from "./AlibabaModelProvider.js";

packages/trueforge/src/db/agentStore.ts

@@ -5,12 +5,12 @@
  * Implementations: PostgresAgentStore and SqliteAgentStore.
  */
 import { AgentSpecSchema, type AgentSpec } from '@truefoundry/trueforge-core/agent-session';
-import type { ResourceName } from '../schemas/common';
+import type { AgentName } from '../schemas/common';
 
 export interface AgentRecord {
   id: string;
   tenant_id: string;
-  name: ResourceName;
+  name: AgentName;
   manifest: AgentSpec;
   /** ISO-8601 UTC instant. */
   created_at: string;
@@ -31,7 +31,7 @@ export type GetAgentInput = { tenant_id: string } & ({ id: string } | { name: st
 
 export interface CreateAgentInput {
   tenant_id: string;
-  name: ResourceName;
+  name: AgentName;
   manifest: AgentSpec;
 }