Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Proxy TrueFoundry skill catalog and return 424 on skill writes (#631)

Bhavesh Patel762ecc09a86c
diff --git a/.changeset/20260908014909-tfy-skills-catalog-proxy.md b/.changeset/20260908014909-tfy-skills-catalog-proxy.md
new file mode 100644
index 000000000..22efde2d2
--- /dev/null
+++ b/.changeset/20260908014909-tfy-skills-catalog-proxy.md
@@ -0,0 +1,7 @@
+---
+"@truefoundry/trueforge": patch
+"@truefoundry/trueforge-core": patch
+"@truefoundry/trueforge-ui": patch
+---
+
+TrueFoundry skills catalog: proxy GET /skills and /skills/versions from ServiceFoundry; settings skill writes return 424. SkillManifest is a type-discriminated oneOf of GitSkill | TrueFoundryRegistrySkill (`type: truefoundry`; name is FQN, display_name is short). AvailableSkill exposes optional metadata (display_name, repository_name, version). AgentSpec skill refs allow opaque FQN names, optional preload (registry), and max 50. UI draft skill mounts map catalog `id` to AgentSpec `name`.
diff --git a/.changeset/20260908212006-regenerate-sdk-from-openapi.md b/.changeset/20260908212006-regenerate-sdk-from-openapi.md
new file mode 100644
index 000000000..efd8ff00f
--- /dev/null
+++ b/.changeset/20260908212006-regenerate-sdk-from-openapi.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index b15204a60..8e7819783 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -193,10 +193,11 @@
"$ref": "#/components/schemas/ResponseFormat"
},
"skills": {
- "description": "Optional name-only skill references. Requires `config.sandbox.enabled: true`.",
+ "description": "Skills used in this agent.",
"items": {
"$ref": "#/components/schemas/Skill"
},
+ "maxItems": 50,
"type": "array"
}
},
@@ -411,8 +412,17 @@
"minLength": 1,
"type": "string"
},
+ "metadata": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Optional skill metadata.",
+ "type": "object"
+ },
"name": {
- "$ref": "#/components/schemas/ResourceName"
+ "description": "Skill name.",
+ "minLength": 1,
+ "type": "string"
}
},
"required": [
@@ -656,7 +666,7 @@
"type": "string"
},
"type": {
- "$ref": "#/components/schemas/SkillType"
+ "$ref": "#/components/schemas/CatalogSkillType"
},
"url": {
"description": "Full HTTPS URL of a GitHub or GitLab repository.",
@@ -674,6 +684,12 @@
],
"type": "object"
},
+ "CatalogSkillType": {
+ "enum": [
+ "git"
+ ],
+ "type": "string"
+ },
"CatalogWellKnownModelProvider": {
"additionalProperties": false,
"properties": {
@@ -934,7 +950,8 @@
"$ref": "#/components/schemas/SkillManifest"
},
"name": {
- "$ref": "#/components/schemas/ResourceName"
+ "minLength": 1,
+ "type": "string"
}
},
"required": [
@@ -1578,6 +1595,51 @@
],
"type": "object"
},
+ "GitSkill": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Concise guidance for when the agent should use the skill.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "path": {
+ "description": "Path to the skill directory within the repository. Omit to use the repository root.",
+ "minLength": 1,
+ "pattern": "^[A-Za-z0-9._\\-/]+$",
+ "type": "string"
+ },
+ "ref": {
+ "description": "Git ref — branch name, tag, or commit SHA.",
+ "minLength": 1,
+ "pattern": "^[A-Za-z0-9._\\-/]+$",
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "git"
+ ],
+ "type": "string"
+ },
+ "url": {
+ "description": "Full HTTPS URL of a GitHub or GitLab repository.",
+ "minLength": 1,
+ "pattern": "^https:\\/\\/(github\\.com\\/[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+|gitlab\\.com\\/[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)+)(\\/|\\.git)?$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "url",
+ "ref",
+ "description"
+ ],
+ "type": "object"
+ },
"GoogleGeminiModelProvider": {
"additionalProperties": false,
"properties": {
@@ -1849,6 +1911,20 @@
],
"type": "object"
},
+ "ListSkillVersionsResponse": {
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/SkillVersion"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"ListSkillsResponse": {
"properties": {
"data": {
@@ -3805,11 +3881,15 @@
"additionalProperties": false,
"properties": {
"name": {
- "description": "Name of a configured skill (also used as the skill directory name in the sandbox).",
- "maxLength": 64,
+ "description": "Skill name.",
"minLength": 1,
- "pattern": "^[A-Za-z0-9._-]+$",
+ "pattern": "^[A-Za-z0-9._\\-/:]+$",
"type": "string"
+ },
+ "preload": {
+ "default": false,
+ "description": "Inline SKILL.md into the prompt.",
+ "type": "boolean"
}
},
"required": [
@@ -3834,6 +3914,23 @@
"type": "object"
},
"SkillManifest": {
+ "discriminator": {
+ "mapping": {
+ "git": "#/components/schemas/GitSkill",
+ "truefoundry": "#/components/schemas/TrueFoundryRegistrySkill"
+ },
+ "propertyName": "type"
+ },
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/GitSkill"
+ },
+ {
+ "$ref": "#/components/schemas/TrueFoundryRegistrySkill"
+ }
+ ]
+ },
+ "SkillVersion": {
"additionalProperties": false,
"properties": {
"description": {
@@ -3841,46 +3938,27 @@
"minLength": 1,
"type": "string"
},
- "name": {
- "$ref": "#/components/schemas/ResourceName"
- },
- "path": {
- "description": "Path to the skill directory within the repository. Omit to use the repository root.",
+ "display_name": {
"minLength": 1,
- "pattern": "^[A-Za-z0-9._\\-/]+$",
"type": "string"
},
- "ref": {
- "description": "Git ref — branch name, tag, or commit SHA.",
+ "name": {
"minLength": 1,
- "pattern": "^[A-Za-z0-9._\\-/]+$",
"type": "string"
},
- "type": {
- "$ref": "#/components/schemas/SkillType"
- },
- "url": {
- "description": "Full HTTPS URL of a GitHub or GitLab repository.",
- "minLength": 1,
- "pattern": "^https:\\/\\/(github\\.com\\/[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+|gitlab\\.com\\/[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)+)(\\/|\\.git)?$",
- "type": "string"
+ "version": {
+ "exclusiveMinimum": 0,
+ "type": "integer"
}
},
"required": [
- "type",
"name",
- "url",
- "ref",
- "description"
+ "display_name",
+ "description",
+ "version"
],
"type": "object"
},
- "SkillType": {
- "enum": [
- "git"
- ],
- "type": "string"
- },
"TextContent": {
"properties": {
"text": {
@@ -4300,6 +4378,48 @@
],
"type": "object"
},
+ "TrueFoundryRegistrySkill": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Concise guidance for when the agent should use the skill.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "display_name": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "name": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "repository_name": {
+ "description": "Repo where the skill is registered.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "truefoundry"
+ ],
+ "type": "string"
+ },
+ "version": {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "display_name",
+ "description",
+ "repository_name",
+ "version"
+ ],
+ "type": "object"
+ },
"TrueFoundrySystemToolInfo": {
"properties": {
"name": {
@@ -8730,6 +8850,16 @@
}
},
"description": "A skill with this name already exists."
+ },
+ "424": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unsupported because skills are managed by an external system."
}
},
"summary": "Create a skill",
@@ -8774,6 +8904,16 @@
}
},
"description": "Invalid request body."
+ },
+ "424": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unsupported because skills are managed by an external system."
}
},
"summary": "Create or replace a skill",
@@ -8821,6 +8961,54 @@
],
"x-fern-sdk-method-name": "list"
}
+ },
+ "/api/v1/skills/versions": {
+ "get": {
+ "description": "Versions for one skill.",
+ "parameters": [
+ {
+ "description": "Skill name.",
+ "in": "query",
+ "name": "name",
+ "required": true,
+ "schema": {
+ "description": "Skill name.",
+ "minLength": 1,
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListSkillVersionsResponse"
+ }
+ }
+ },
+ "description": "Skill versions."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Authentication required."
+ }
+ },
+ "summary": "List skill versions",
+ "tags": [
+ "Skills"
+ ],
+ "x-fern-sdk-group-name": [
+ "skills"
+ ],
+ "x-fern-sdk-method-name": "list_versions"
+ }
}
},
"security": [
diff --git a/docs/openapi.json b/docs/openapi.json
index b15204a60..8e7819783 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -193,10 +193,11 @@
"$ref": "#/components/schemas/ResponseFormat"
},
"skills": {
- "description": "Optional name-only skill references. Requires `config.sandbox.enabled: true`.",
+ "description": "Skills used in this agent.",
"items": {
"$ref": "#/components/schemas/Skill"
},
+ "maxItems": 50,
"type": "array"
}
},
@@ -411,8 +412,17 @@
"minLength": 1,
"type": "string"
},
+ "metadata": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Optional skill metadata.",
+ "type": "object"
+ },
"name": {
- "$ref": "#/components/schemas/ResourceName"
+ "description": "Skill name.",
+ "minLength": 1,
+ "type": "string"
}
},
"required": [
@@ -656,7 +666,7 @@
"type": "string"
},
"type": {
- "$ref": "#/components/schemas/SkillType"
+ "$ref": "#/components/schemas/CatalogSkillType"
},
"url": {
"description": "Full HTTPS URL of a GitHub or GitLab repository.",
@@ -674,6 +684,12 @@
],
"type": "object"
},
+ "CatalogSkillType": {
+ "enum": [
+ "git"
+ ],
+ "type": "string"
+ },
"CatalogWellKnownModelProvider": {
"additionalProperties": false,
"properties": {
@@ -934,7 +950,8 @@
"$ref": "#/components/schemas/SkillManifest"
},
"name": {
- "$ref": "#/components/schemas/ResourceName"
+ "minLength": 1,
+ "type": "string"
}
},
"required": [
@@ -1578,6 +1595,51 @@
],
"type": "object"
},
+ "GitSkill": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Concise guidance for when the agent should use the skill.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "path": {
+ "description": "Path to the skill directory within the repository. Omit to use the repository root.",
+ "minLength": 1,
+ "pattern": "^[A-Za-z0-9._\\-/]+$",
+ "type": "string"
+ },
+ "ref": {
+ "description": "Git ref — branch name, tag, or commit SHA.",
+ "minLength": 1,
+ "pattern": "^[A-Za-z0-9._\\-/]+$",
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "git"
+ ],
+ "type": "string"
+ },
+ "url": {
+ "description": "Full HTTPS URL of a GitHub or GitLab repository.",
+ "minLength": 1,
+ "pattern": "^https:\\/\\/(github\\.com\\/[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+|gitlab\\.com\\/[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)+)(\\/|\\.git)?$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "url",
+ "ref",
+ "description"
+ ],
+ "type": "object"
+ },
"GoogleGeminiModelProvider": {
"additionalProperties": false,
"properties": {
@@ -1849,6 +1911,20 @@
],
"type": "object"
},
+ "ListSkillVersionsResponse": {
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/SkillVersion"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"ListSkillsResponse": {
"properties": {
"data": {
@@ -3805,11 +3881,15 @@
"additionalProperties": false,
"properties": {
"name": {
- "description": "Name of a configured skill (also used as the skill directory name in the sandbox).",
- "maxLength": 64,
+ "description": "Skill name.",
"minLength": 1,
- "pattern": "^[A-Za-z0-9._-]+$",
+ "pattern": "^[A-Za-z0-9._\\-/:]+$",
"type": "string"
+ },
+ "preload": {
+ "default": false,
+ "description": "Inline SKILL.md into the prompt.",
+ "type": "boolean"
}
},
"required": [
@@ -3834,6 +3914,23 @@
"type": "object"
},
"SkillManifest": {
+ "discriminator": {
+ "mapping": {
+ "git": "#/components/schemas/GitSkill",
+ "truefoundry": "#/components/schemas/TrueFoundryRegistrySkill"
+ },
+ "propertyName": "type"
+ },
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/GitSkill"
+ },
+ {
+ "$ref": "#/components/schemas/TrueFoundryRegistrySkill"
+ }
+ ]
+ },
+ "SkillVersion": {
"additionalProperties": false,
"properties": {
"description": {
@@ -3841,46 +3938,27 @@
"minLength": 1,
"type": "string"
},
- "name": {
- "$ref": "#/components/schemas/ResourceName"
- },
- "path": {
- "description": "Path to the skill directory within the repository. Omit to use the repository root.",
+ "display_name": {
"minLength": 1,
- "pattern": "^[A-Za-z0-9._\\-/]+$",
"type": "string"
},
- "ref": {
- "description": "Git ref — branch name, tag, or commit SHA.",
+ "name": {
"minLength": 1,
- "pattern": "^[A-Za-z0-9._\\-/]+$",
"type": "string"
},
- "type": {
- "$ref": "#/components/schemas/SkillType"
- },
- "url": {
- "description": "Full HTTPS URL of a GitHub or GitLab repository.",
- "minLength": 1,
- "pattern": "^https:\\/\\/(github\\.com\\/[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+|gitlab\\.com\\/[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)+)(\\/|\\.git)?$",
- "type": "string"
+ "version": {
+ "exclusiveMinimum": 0,
+ "type": "integer"
}
},
"required": [
- "type",
"name",
- "url",
- "ref",
- "description"
+ "display_name",
+ "description",
+ "version"
],
"type": "object"
},
- "SkillType": {
- "enum": [
- "git"
- ],
- "type": "string"
- },
"TextContent": {
"properties": {
"text": {
@@ -4300,6 +4378,48 @@
],
"type": "object"
},
+ "TrueFoundryRegistrySkill": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Concise guidance for when the agent should use the skill.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "display_name": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "name": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "repository_name": {
+ "description": "Repo where the skill is registered.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "truefoundry"
+ ],
+ "type": "string"
+ },
+ "version": {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "display_name",
+ "description",
+ "repository_name",
+ "version"
+ ],
+ "type": "object"
+ },
"TrueFoundrySystemToolInfo": {
"properties": {
"name": {
@@ -8730,6 +8850,16 @@
}
},
"description": "A skill with this name already exists."
+ },
+ "424": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unsupported because skills are managed by an external system."
}
},
"summary": "Create a skill",
@@ -8774,6 +8904,16 @@
}
},
"description": "Invalid request body."
+ },
+ "424": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Unsupported because skills are managed by an external system."
}
},
"summary": "Create or replace a skill",
@@ -8821,6 +8961,54 @@
],
"x-fern-sdk-method-name": "list"
}
+ },
+ "/api/v1/skills/versions": {
+ "get": {
+ "description": "Versions for one skill.",
+ "parameters": [
+ {
+ "description": "Skill name.",
+ "in": "query",
+ "name": "name",
+ "required": true,
+ "schema": {
+ "description": "Skill name.",
+ "minLength": 1,
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListSkillVersionsResponse"
+ }
+ }
+ },
+ "description": "Skill versions."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Authentication required."
+ }
+ },
+ "summary": "List skill versions",
+ "tags": [
+ "Skills"
+ ],
+ "x-fern-sdk-group-name": [
+ "skills"
+ ],
+ "x-fern-sdk-method-name": "list_versions"
+ }
}
},
"security": [
diff --git a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
index df5caf9f7..f6c126262 100644
--- a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
@@ -1,4 +1,4 @@
-/** DB AgentSpec wire schema — FQN model names and name-only skill refs. */
+/** DB AgentSpec wire schema — FQN model names and skill refs (name + optional preload). */
import { z } from '@hono/zod-openapi';
import {
DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,
@@ -221,22 +221,24 @@ export const RuntimeConfigSchema = z
.openapi('RuntimeConfig');
// --- Skills ---
-// Name-only refs; DB sessions expand mount fields from ISkillStore at turn time.
+// Name (+ optional preload) refs; the skill store expands mounts at turn time.
-const SKILL_NAME_REGEX = /^[A-Za-z0-9._-]+$/;
+const SKILL_NAME_REGEX = /^[A-Za-z0-9._\-/:]+$/;
-/** Name-only skill selection; mount fields come from the skill store. */
+const MAX_AGENT_SKILLS = 50;
+
+/** Skill selection; mount fields come from the skill store. */
const SkillSchema = z
.object({
name: z
.string()
.trim()
.min(1)
- .max(64)
- .regex(SKILL_NAME_REGEX, 'Name may only contain letters, numbers, ".", "_", and "-"')
+ .regex(SKILL_NAME_REGEX, 'Name may only contain letters, numbers, ".", "_", "-", "/", and ":"')
.refine(v => v !== '.' && v !== '..', 'Name must not be "." or ".."')
.refine(v => !v.startsWith('.tfy-'), 'Name must not use the reserved ".tfy-" prefix')
- .describe('Name of a configured skill (also used as the skill directory name in the sandbox).'),
+ .describe('Skill name.'),
+ preload: z.boolean().optional().default(false).describe('Inline SKILL.md into the prompt.'),
})
.strict()
.openapi('Skill');
@@ -272,10 +274,7 @@ export const AgentSpecSchema = z
.optional()
.describe('Optional MCP servers attached by configured name.'),
response_format: ResponseFormatSchema.optional(),
- skills: z
- .array(SkillSchema)
- .optional()
- .describe('Optional name-only skill references. Requires `config.sandbox.enabled: true`.'),
+ skills: z.array(SkillSchema).max(MAX_AGENT_SKILLS).optional().describe('Skills used in this agent.'),
// Factory must parse so nested RuntimeConfig field defaults materialize.
config: RuntimeConfigSchema.default(() => RuntimeConfigSchema.parse({})),
})
diff --git a/packages/trueforge-core/tests/agent-session/agentSpecSkills.test.ts b/packages/trueforge-core/tests/agent-session/agentSpecSkills.test.ts
index d82cfaf5a..dc75bbbc5 100644
--- a/packages/trueforge-core/tests/agent-session/agentSpecSkills.test.ts
+++ b/packages/trueforge-core/tests/agent-session/agentSpecSkills.test.ts
@@ -1,19 +1,44 @@
import { AgentSpecSchema } from '../../src/agent-session/schemas/agentSpec';
describe('AgentSpecSchema skills', () => {
- it('accepts name-only Skill entries', () => {
+ it('accepts name-only Skill entries and defaults preload to false', () => {
const parsed = AgentSpecSchema.parse({
model: { name: 'test-provider/test-model' },
skills: [{ name: 'my-skill' }],
});
- expect(parsed.skills).toEqual([{ name: 'my-skill' }]);
+ expect(parsed.skills).toEqual([{ name: 'my-skill', preload: false }]);
});
- it('rejects skill mounts with extra fields', () => {
+ it('accepts opaque skill names including registry FQNs', () => {
+ const fqn = 'agent-skill:acme/team-a/echo:3';
+ const parsed = AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ skills: [{ name: fqn, preload: true }],
+ });
+ expect(parsed.skills).toEqual([{ name: fqn, preload: true }]);
+ });
+
+ it('rejects skill names with disallowed characters', () => {
+ const result = AgentSpecSchema.safeParse({
+ model: { name: 'test-provider/test-model' },
+ skills: [{ name: 'bad name' }],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects skill mounts with unknown fields', () => {
const result = AgentSpecSchema.safeParse({
model: { name: 'test-provider/test-model' },
skills: [{ name: 'my-skill', type: 'git', url: 'https://github.com/acme/skills' }],
});
expect(result.success).toBe(false);
});
+
+ it('rejects more than 50 skills', () => {
+ const result = AgentSpecSchema.safeParse({
+ model: { name: 'test-provider/test-model' },
+ skills: Array.from({ length: 51 }, (_, i) => ({ name: `skill-${String(i)}` })),
+ });
+ expect(result.success).toBe(false);
+ });
});
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index f188cbeb4..41fe28921 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -2344,6 +2344,71 @@ await client.skills.list();
</dl>
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.skills.<a href="/src/api/resources/skills/client/Client.ts">listVersions</a>({ ...params }) -> TrueForge.ListSkillVersionsResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Versions for one skill.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.skills.listVersions({
+ name: "name"
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request:** `TrueForge.ListVersionsSkillsRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SkillsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
</dd>
</dl>
</details>
diff --git a/packages/trueforge-sdk/src/api/resources/index.ts b/packages/trueforge-sdk/src/api/resources/index.ts
index 3d97a276c..c337b9722 100644
--- a/packages/trueforge-sdk/src/api/resources/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/index.ts
@@ -12,4 +12,5 @@ export * as server from "./server/index.js";
export * from "./sessions/client/requests/index.js";
export * as sessions from "./sessions/index.js";
export * as settings from "./settings/index.js";
+export * from "./skills/client/requests/index.js";
export * as skills from "./skills/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/settings/resources/skills/client/Client.ts b/packages/trueforge-sdk/src/api/resources/settings/resources/skills/client/Client.ts
index 5238ac92a..592178bee 100644
--- a/packages/trueforge-sdk/src/api/resources/settings/resources/skills/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/settings/resources/skills/client/Client.ts
@@ -121,6 +121,7 @@ export class SkillsClient {
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ConflictError}
+ * @throws {@link TrueForge.FailedDependencyError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -215,6 +216,17 @@ export class SkillsClient {
}),
_response.rawResponse,
);
+ case 424:
+ throw new TrueForge.FailedDependencyError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
@@ -234,6 +246,7 @@ export class SkillsClient {
* @param {SkillsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
+ * @throws {@link TrueForge.FailedDependencyError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -317,6 +330,17 @@ export class SkillsClient {
}),
_response.rawResponse,
);
+ case 424:
+ throw new TrueForge.FailedDependencyError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
diff --git a/packages/trueforge-sdk/src/api/resources/skills/client/Client.ts b/packages/trueforge-sdk/src/api/resources/skills/client/Client.ts
index 4fc7f8f48..af0378ec5 100644
--- a/packages/trueforge-sdk/src/api/resources/skills/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/skills/client/Client.ts
@@ -101,4 +101,97 @@ export class SkillsClient {
return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/skills");
}
+
+ /**
+ * Versions for one skill.
+ *
+ * @param {TrueForge.ListVersionsSkillsRequest} request
+ * @param {SkillsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.skills.listVersions({
+ * name: "name"
+ * })
+ */
+ public listVersions(
+ request: TrueForge.ListVersionsSkillsRequest,
+ requestOptions?: SkillsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.ListSkillVersionsResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__listVersions(request, requestOptions));
+ }
+
+ private async __listVersions(
+ request: TrueForge.ListVersionsSkillsRequest,
+ requestOptions?: SkillsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.ListSkillVersionsResponse>> {
+ const { name } = request;
+ const _queryParams: Record<string, unknown> = {
+ name,
+ };
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ "api/v1/skills/versions",
+ ),
+ method: "GET",
+ headers: _headers,
+ queryString: core.url
+ .queryBuilder()
+ .addMany(_queryParams)
+ .mergeAdditional(requestOptions?.queryParams)
+ .build(),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.ListSkillVersionsResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/skills/versions");
+ }
}
diff --git a/packages/trueforge-sdk/src/api/resources/skills/client/index.ts b/packages/trueforge-sdk/src/api/resources/skills/client/index.ts
index cb0ff5c3b..195f9aa8a 100644
--- a/packages/trueforge-sdk/src/api/resources/skills/client/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/skills/client/index.ts
@@ -1 +1 @@
-export {};
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/skills/client/requests/ListVersionsSkillsRequest.ts b/packages/trueforge-sdk/src/api/resources/skills/client/requests/ListVersionsSkillsRequest.ts
new file mode 100644
index 000000000..286cf23cd
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/skills/client/requests/ListVersionsSkillsRequest.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ * {
+ * name: "name"
+ * }
+ */
+export interface ListVersionsSkillsRequest {
+ /** Skill name. */
+ name: string;
+}
diff --git a/packages/trueforge-sdk/src/api/resources/skills/client/requests/index.ts b/packages/trueforge-sdk/src/api/resources/skills/client/requests/index.ts
new file mode 100644
index 000000000..f7bdbe76b
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/skills/client/requests/index.ts
@@ -0,0 +1 @@
+export type { ListVersionsSkillsRequest } from "./ListVersionsSkillsRequest.js";
diff --git a/packages/trueforge-sdk/src/api/types/AgentSpec.ts b/packages/trueforge-sdk/src/api/types/AgentSpec.ts
index 62ee54f6d..2c8956013 100644
--- a/packages/trueforge-sdk/src/api/types/AgentSpec.ts
+++ b/packages/trueforge-sdk/src/api/types/AgentSpec.ts
@@ -15,6 +15,6 @@ export interface AgentSpec {
messages?: TrueForge.InitialUserMessage[];
model: TrueForge.Model;
responseFormat?: TrueForge.ResponseFormat;
- /** Optional name-only skill references. Requires `config.sandbox.enabled: true`. */
+ /** Skills used in this agent. */
skills?: TrueForge.Skill[];
}
diff --git a/packages/trueforge-sdk/src/api/types/AvailableSkill.ts b/packages/trueforge-sdk/src/api/types/AvailableSkill.ts
index a633f11fb..caabe5531 100644
--- a/packages/trueforge-sdk/src/api/types/AvailableSkill.ts
+++ b/packages/trueforge-sdk/src/api/types/AvailableSkill.ts
@@ -1,9 +1,10 @@
// This file was auto-generated by Fern from our API Definition.
-import type * as TrueForge from "../index.js";
-
export interface AvailableSkill {
/** Concise guidance for when the agent should use the skill. */
description: string;
- name: TrueForge.ResourceName;
+ /** Optional skill metadata. */
+ metadata?: Record<string, string>;
+ /** Skill name. */
+ name: string;
}
diff --git a/packages/trueforge-sdk/src/api/types/CatalogSkill.ts b/packages/trueforge-sdk/src/api/types/CatalogSkill.ts
index c2a97aa87..ab8453e45 100644
--- a/packages/trueforge-sdk/src/api/types/CatalogSkill.ts
+++ b/packages/trueforge-sdk/src/api/types/CatalogSkill.ts
@@ -10,7 +10,7 @@ export interface CatalogSkill {
path?: string;
/** Git ref — branch name, tag, or commit SHA. */
ref: string;
- type: TrueForge.SkillType;
+ type: TrueForge.CatalogSkillType;
/** Full HTTPS URL of a GitHub or GitLab repository. */
url: string;
}
diff --git a/packages/trueforge-sdk/src/api/types/SkillType.ts b/packages/trueforge-sdk/src/api/types/CatalogSkillType.ts
similarity index 63%
rename from packages/trueforge-sdk/src/api/types/SkillType.ts
rename to packages/trueforge-sdk/src/api/types/CatalogSkillType.ts
index 934c9527a..c56d732ab 100644
--- a/packages/trueforge-sdk/src/api/types/SkillType.ts
+++ b/packages/trueforge-sdk/src/api/types/CatalogSkillType.ts
@@ -1,3 +1,3 @@
// This file was auto-generated by Fern from our API Definition.
-export type SkillType = "git";
+export type CatalogSkillType = "git";
diff --git a/packages/trueforge-sdk/src/api/types/ConfiguredSkill.ts b/packages/trueforge-sdk/src/api/types/ConfiguredSkill.ts
index 3bfe0edfd..bd5caea39 100644
--- a/packages/trueforge-sdk/src/api/types/ConfiguredSkill.ts
+++ b/packages/trueforge-sdk/src/api/types/ConfiguredSkill.ts
@@ -4,5 +4,5 @@ import type * as TrueForge from "../index.js";
export interface ConfiguredSkill {
manifest: TrueForge.SkillManifest;
- name: TrueForge.ResourceName;
+ name: string;
}
diff --git a/packages/trueforge-sdk/src/api/types/GitSkill.ts b/packages/trueforge-sdk/src/api/types/GitSkill.ts
new file mode 100644
index 000000000..e30ca518a
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/GitSkill.ts
@@ -0,0 +1,16 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface GitSkill {
+ /** Concise guidance for when the agent should use the skill. */
+ description: string;
+ name: TrueForge.ResourceName;
+ /** Path to the skill directory within the repository. Omit to use the repository root. */
+ path?: string;
+ /** Git ref — branch name, tag, or commit SHA. */
+ ref: string;
+ type: "git";
+ /** Full HTTPS URL of a GitHub or GitLab repository. */
+ url: string;
+}
diff --git a/packages/trueforge-sdk/src/api/types/ListSkillVersionsResponse.ts b/packages/trueforge-sdk/src/api/types/ListSkillVersionsResponse.ts
new file mode 100644
index 000000000..cf5524100
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/ListSkillVersionsResponse.ts
@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface ListSkillVersionsResponse {
+ data: TrueForge.SkillVersion[];
+}
diff --git a/packages/trueforge-sdk/src/api/types/Skill.ts b/packages/trueforge-sdk/src/api/types/Skill.ts
index 00b7f916e..dcfbc1f59 100644
--- a/packages/trueforge-sdk/src/api/types/Skill.ts
+++ b/packages/trueforge-sdk/src/api/types/Skill.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface Skill {
- /** Name of a configured skill (also used as the skill directory name in the sandbox). */
+ /** Skill name. */
name: string;
+ /** Inline SKILL.md into the prompt. */
+ preload?: boolean;
}
diff --git a/packages/trueforge-sdk/src/api/types/SkillManifest.ts b/packages/trueforge-sdk/src/api/types/SkillManifest.ts
index be259a29a..504ac8fef 100644
--- a/packages/trueforge-sdk/src/api/types/SkillManifest.ts
+++ b/packages/trueforge-sdk/src/api/types/SkillManifest.ts
@@ -2,15 +2,4 @@
import type * as TrueForge from "../index.js";
-export interface SkillManifest {
- /** Concise guidance for when the agent should use the skill. */
- description: string;
- name: TrueForge.ResourceName;
- /** Path to the skill directory within the repository. Omit to use the repository root. */
- path?: string;
- /** Git ref — branch name, tag, or commit SHA. */
- ref: string;
- type: TrueForge.SkillType;
- /** Full HTTPS URL of a GitHub or GitLab repository. */
- url: string;
-}
+export type SkillManifest = TrueForge.GitSkill | TrueForge.TrueFoundryRegistrySkill;
diff --git a/packages/trueforge-sdk/src/api/types/SkillVersion.ts b/packages/trueforge-sdk/src/api/types/SkillVersion.ts
new file mode 100644
index 000000000..c9f70b663
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SkillVersion.ts
@@ -0,0 +1,9 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface SkillVersion {
+ /** Concise guidance for when the agent should use the skill. */
+ description: string;
+ displayName: string;
+ name: string;
+ version: number;
+}
diff --git a/packages/trueforge-sdk/src/api/types/TrueFoundryRegistrySkill.ts b/packages/trueforge-sdk/src/api/types/TrueFoundryRegistrySkill.ts
new file mode 100644
index 000000000..6651469f3
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/TrueFoundryRegistrySkill.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface TrueFoundryRegistrySkill {
+ /** Concise guidance for when the agent should use the skill. */
+ description: string;
+ displayName: string;
+ name: string;
+ /** Repo where the skill is registered. */
+ repositoryName: string;
+ type: "truefoundry";
+ version: number;
+}
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index 18a612fbb..97e64b221 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -27,6 +27,7 @@ export * from "./CatalogModel.js";
export * from "./CatalogModelProvider.js";
export * from "./CatalogSandboxProvider.js";
export * from "./CatalogSkill.js";
+export * from "./CatalogSkillType.js";
export * from "./CatalogWellKnownModelProvider.js";
export * from "./CatalogWellKnownModelProviderType.js";
export * from "./ChatCompletionChunkDeltaToolCall.js";
@@ -76,6 +77,7 @@ export * from "./GetSessionResponse.js";
export * from "./GetSkillCatalogResponse.js";
export * from "./GetSkillResponse.js";
export * from "./GetTurnResponse.js";
+export * from "./GitSkill.js";
export * from "./GoogleGeminiModelProvider.js";
export * from "./InitialUserMessage.js";
export * from "./InputTokensCompactionTrigger.js";
@@ -93,6 +95,7 @@ export * from "./ListSessionEventsResponse.js";
export * from "./ListSessionsOrder.js";
export * from "./ListSessionsResponse.js";
export * from "./ListSkillsResponse.js";
+export * from "./ListSkillVersionsResponse.js";
export * from "./ListTurnEventsOrder.js";
export * from "./ListTurnEventsResponse.js";
export * from "./ListTurnsResponse.js";
@@ -180,7 +183,7 @@ export * from "./SettingsCapability.js";
export * from "./Skill.js";
export * from "./SkillCapability.js";
export * from "./SkillManifest.js";
-export * from "./SkillType.js";
+export * from "./SkillVersion.js";
export * from "./TextContent.js";
export * from "./ThreadCreatedEvent.js";
export * from "./ThreadDoneEvent.js";
@@ -197,6 +200,7 @@ export * from "./ToolInfo.js";
export * from "./ToolResponseEvent.js";
export * from "./ToolResponseRequiredEvent.js";
export * from "./TrueFoundryModelProvider.js";
+export * from "./TrueFoundryRegistrySkill.js";
export * from "./TrueFoundrySystemToolInfo.js";
export * from "./Turn.js";
export * from "./TurnCreatedEvent.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/AvailableSkill.ts b/packages/trueforge-sdk/src/serialization/types/AvailableSkill.ts
index c69181bec..2c64ed54a 100644
--- a/packages/trueforge-sdk/src/serialization/types/AvailableSkill.ts
+++ b/packages/trueforge-sdk/src/serialization/types/AvailableSkill.ts
@@ -3,17 +3,18 @@
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";
export const AvailableSkill: core.serialization.ObjectSchema<serializers.AvailableSkill.Raw, TrueForge.AvailableSkill> =
core.serialization.object({
description: core.serialization.string(),
- name: ResourceName,
+ metadata: core.serialization.record(core.serialization.string(), core.serialization.string()).optional(),
+ name: core.serialization.string(),
});
export declare namespace AvailableSkill {
export interface Raw {
description: string;
- name: ResourceName.Raw;
+ metadata?: Record<string, string> | null;
+ name: string;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/CatalogSkill.ts b/packages/trueforge-sdk/src/serialization/types/CatalogSkill.ts
index 2b226f16b..49ed0de86 100644
--- a/packages/trueforge-sdk/src/serialization/types/CatalogSkill.ts
+++ b/packages/trueforge-sdk/src/serialization/types/CatalogSkill.ts
@@ -3,8 +3,8 @@
import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
+import { CatalogSkillType } from "./CatalogSkillType.js";
import { ResourceName } from "./ResourceName.js";
-import { SkillType } from "./SkillType.js";
export const CatalogSkill: core.serialization.ObjectSchema<serializers.CatalogSkill.Raw, TrueForge.CatalogSkill> =
core.serialization.object({
@@ -12,7 +12,7 @@ export const CatalogSkill: core.serialization.ObjectSchema<serializers.CatalogSk
name: ResourceName,
path: core.serialization.string().optional(),
ref: core.serialization.string(),
- type: SkillType,
+ type: CatalogSkillType,
url: core.serialization.string(),
});
@@ -22,7 +22,7 @@ export declare namespace CatalogSkill {
name: ResourceName.Raw;
path?: string | null;
ref: string;
- type: SkillType.Raw;
+ type: CatalogSkillType.Raw;
url: string;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/SkillType.ts b/packages/trueforge-sdk/src/serialization/types/CatalogSkillType.ts
similarity index 63%
rename from packages/trueforge-sdk/src/serialization/types/SkillType.ts
rename to packages/trueforge-sdk/src/serialization/types/CatalogSkillType.ts
index d38dde18d..3f311618d 100644
--- a/packages/trueforge-sdk/src/serialization/types/SkillType.ts
+++ b/packages/trueforge-sdk/src/serialization/types/CatalogSkillType.ts
@@ -4,9 +4,9 @@ import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
-export const SkillType: core.serialization.Schema<serializers.SkillType.Raw, TrueForge.SkillType> =
+export const CatalogSkillType: core.serialization.Schema<serializers.CatalogSkillType.Raw, TrueForge.CatalogSkillType> =
core.serialization.stringLiteral("git");
-export declare namespace SkillType {
+export declare namespace CatalogSkillType {
export type Raw = "git";
}
diff --git a/packages/trueforge-sdk/src/serialization/types/ConfiguredSkill.ts b/packages/trueforge-sdk/src/serialization/types/ConfiguredSkill.ts
index e3c687414..0477016d6 100644
--- a/packages/trueforge-sdk/src/serialization/types/ConfiguredSkill.ts
+++ b/packages/trueforge-sdk/src/serialization/types/ConfiguredSkill.ts
@@ -3,7 +3,6 @@
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 { SkillManifest } from "./SkillManifest.js";
export const ConfiguredSkill: core.serialization.ObjectSchema<
@@ -11,12 +10,12 @@ export const ConfiguredSkill: core.serialization.ObjectSchema<
TrueForge.ConfiguredSkill
> = core.serialization.object({
manifest: SkillManifest,
- name: ResourceName,
+ name: core.serialization.string(),
});
export declare namespace ConfiguredSkill {
export interface Raw {
manifest: SkillManifest.Raw;
- name: ResourceName.Raw;
+ name: string;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/GitSkill.ts b/packages/trueforge-sdk/src/serialization/types/GitSkill.ts
new file mode 100644
index 000000000..0929b88a8
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/GitSkill.ts
@@ -0,0 +1,27 @@
+// 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";
+import { ResourceName } from "./ResourceName.js";
+
+export const GitSkill: core.serialization.ObjectSchema<serializers.GitSkill.Raw, TrueForge.GitSkill> =
+ core.serialization.object({
+ description: core.serialization.string(),
+ name: ResourceName,
+ path: core.serialization.string().optional(),
+ ref: core.serialization.string(),
+ type: core.serialization.stringLiteral("git"),
+ url: core.serialization.string(),
+ });
+
+export declare namespace GitSkill {
+ export interface Raw {
+ description: string;
+ name: ResourceName.Raw;
+ path?: string | null;
+ ref: string;
+ type: "git";
+ url: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/ListSkillVersionsResponse.ts b/packages/trueforge-sdk/src/serialization/types/ListSkillVersionsResponse.ts
new file mode 100644
index 000000000..6dfe6b225
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/ListSkillVersionsResponse.ts
@@ -0,0 +1,19 @@
+// 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";
+import { SkillVersion } from "./SkillVersion.js";
+
+export const ListSkillVersionsResponse: core.serialization.ObjectSchema<
+ serializers.ListSkillVersionsResponse.Raw,
+ TrueForge.ListSkillVersionsResponse
+> = core.serialization.object({
+ data: core.serialization.list(SkillVersion),
+});
+
+export declare namespace ListSkillVersionsResponse {
+ export interface Raw {
+ data: SkillVersion.Raw[];
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/Skill.ts b/packages/trueforge-sdk/src/serialization/types/Skill.ts
index 71dc42c58..7a4b60488 100644
--- a/packages/trueforge-sdk/src/serialization/types/Skill.ts
+++ b/packages/trueforge-sdk/src/serialization/types/Skill.ts
@@ -7,11 +7,13 @@ import type * as serializers from "../index.js";
export const Skill: core.serialization.ObjectSchema<serializers.Skill.Raw, TrueForge.Skill> = core.serialization.object(
{
name: core.serialization.string(),
+ preload: core.serialization.boolean().optional(),
},
);
export declare namespace Skill {
export interface Raw {
name: string;
+ preload?: boolean | null;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/SkillManifest.ts b/packages/trueforge-sdk/src/serialization/types/SkillManifest.ts
index 2b832a937..d38442e35 100644
--- a/packages/trueforge-sdk/src/serialization/types/SkillManifest.ts
+++ b/packages/trueforge-sdk/src/serialization/types/SkillManifest.ts
@@ -3,26 +3,12 @@
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 { SkillType } from "./SkillType.js";
+import { GitSkill } from "./GitSkill.js";
+import { TrueFoundryRegistrySkill } from "./TrueFoundryRegistrySkill.js";
-export const SkillManifest: core.serialization.ObjectSchema<serializers.SkillManifest.Raw, TrueForge.SkillManifest> =
- core.serialization.object({
- description: core.serialization.string(),
- name: ResourceName,
- path: core.serialization.string().optional(),
- ref: core.serialization.string(),
- type: SkillType,
- url: core.serialization.string(),
- });
+export const SkillManifest: core.serialization.Schema<serializers.SkillManifest.Raw, TrueForge.SkillManifest> =
+ core.serialization.undiscriminatedUnion([GitSkill, TrueFoundryRegistrySkill]);
export declare namespace SkillManifest {
- export interface Raw {
- description: string;
- name: ResourceName.Raw;
- path?: string | null;
- ref: string;
- type: SkillType.Raw;
- url: string;
- }
+ export type Raw = GitSkill.Raw | TrueFoundryRegistrySkill.Raw;
}
diff --git a/packages/trueforge-sdk/src/serialization/types/SkillVersion.ts b/packages/trueforge-sdk/src/serialization/types/SkillVersion.ts
new file mode 100644
index 000000000..6305736cd
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SkillVersion.ts
@@ -0,0 +1,22 @@
+// 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 SkillVersion: core.serialization.ObjectSchema<serializers.SkillVersion.Raw, TrueForge.SkillVersion> =
+ core.serialization.object({
+ description: core.serialization.string(),
+ displayName: core.serialization.property("display_name", core.serialization.string()),
+ name: core.serialization.string(),
+ version: core.serialization.number(),
+ });
+
+export declare namespace SkillVersion {
+ export interface Raw {
+ description: string;
+ display_name: string;
+ name: string;
+ version: number;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/TrueFoundryRegistrySkill.ts b/packages/trueforge-sdk/src/serialization/types/TrueFoundryRegistrySkill.ts
new file mode 100644
index 000000000..53312d274
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/TrueFoundryRegistrySkill.ts
@@ -0,0 +1,28 @@
+// 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 TrueFoundryRegistrySkill: core.serialization.ObjectSchema<
+ serializers.TrueFoundryRegistrySkill.Raw,
+ TrueForge.TrueFoundryRegistrySkill
+> = core.serialization.object({
+ description: core.serialization.string(),
+ displayName: core.serialization.property("display_name", core.serialization.string()),
+ name: core.serialization.string(),
+ repositoryName: core.serialization.property("repository_name", core.serialization.string()),
+ type: core.serialization.stringLiteral("truefoundry"),
+ version: core.serialization.number(),
+});
+
+export declare namespace TrueFoundryRegistrySkill {
+ export interface Raw {
+ description: string;
+ display_name: string;
+ name: string;
+ repository_name: string;
+ type: "truefoundry";
+ version: number;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index 18a612fbb..97e64b221 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -27,6 +27,7 @@ export * from "./CatalogModel.js";
export * from "./CatalogModelProvider.js";
export * from "./CatalogSandboxProvider.js";
export * from "./CatalogSkill.js";
+export * from "./CatalogSkillType.js";
export * from "./CatalogWellKnownModelProvider.js";
export * from "./CatalogWellKnownModelProviderType.js";
export * from "./ChatCompletionChunkDeltaToolCall.js";
@@ -76,6 +77,7 @@ export * from "./GetSessionResponse.js";
export * from "./GetSkillCatalogResponse.js";
export * from "./GetSkillResponse.js";
export * from "./GetTurnResponse.js";
+export * from "./GitSkill.js";
export * from "./GoogleGeminiModelProvider.js";
export * from "./InitialUserMessage.js";
export * from "./InputTokensCompactionTrigger.js";
@@ -93,6 +95,7 @@ export * from "./ListSessionEventsResponse.js";
export * from "./ListSessionsOrder.js";
export * from "./ListSessionsResponse.js";
export * from "./ListSkillsResponse.js";
+export * from "./ListSkillVersionsResponse.js";
export * from "./ListTurnEventsOrder.js";
export * from "./ListTurnEventsResponse.js";
export * from "./ListTurnsResponse.js";
@@ -180,7 +183,7 @@ export * from "./SettingsCapability.js";
export * from "./Skill.js";
export * from "./SkillCapability.js";
export * from "./SkillManifest.js";
-export * from "./SkillType.js";
+export * from "./SkillVersion.js";
export * from "./TextContent.js";
export * from "./ThreadCreatedEvent.js";
export * from "./ThreadDoneEvent.js";
@@ -197,6 +200,7 @@ export * from "./ToolInfo.js";
export * from "./ToolResponseEvent.js";
export * from "./ToolResponseRequiredEvent.js";
export * from "./TrueFoundryModelProvider.js";
+export * from "./TrueFoundryRegistrySkill.js";
export * from "./TrueFoundrySystemToolInfo.js";
export * from "./Turn.js";
export * from "./TurnCreatedEvent.js";
diff --git a/packages/trueforge-sdk/tests/wire/settings/skills.test.ts b/packages/trueforge-sdk/tests/wire/settings/skills.test.ts
index 6dc8116a9..d21edc6a0 100644
--- a/packages/trueforge-sdk/tests/wire/settings/skills.test.ts
+++ b/packages/trueforge-sdk/tests/wire/settings/skills.test.ts
@@ -190,6 +190,34 @@ describe("SkillsClient", () => {
}).rejects.toThrow(TrueForgeTypes.ConflictError);
});
+ test("create (4)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { description: "x", name: "xy", ref: "x", type: "git", url: "x" } };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/settings/skills")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(424)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.skills.create({
+ manifest: {
+ description: "x",
+ name: "xy",
+ ref: "x",
+ type: "git",
+ url: "x",
+ },
+ });
+ }).rejects.toThrow(TrueForgeTypes.FailedDependencyError);
+ });
+
test("create_or_update (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
@@ -270,4 +298,32 @@ describe("SkillsClient", () => {
});
}).rejects.toThrow(TrueForgeTypes.BadRequestError);
});
+
+ test("create_or_update (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { manifest: { description: "x", name: "xy", ref: "x", type: "git", url: "x" } };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .put("/api/v1/settings/skills")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(424)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.skills.createOrUpdate({
+ manifest: {
+ description: "x",
+ name: "xy",
+ ref: "x",
+ type: "git",
+ url: "x",
+ },
+ });
+ }).rejects.toThrow(TrueForgeTypes.FailedDependencyError);
+ });
});
diff --git a/packages/trueforge-sdk/tests/wire/skills.test.ts b/packages/trueforge-sdk/tests/wire/skills.test.ts
index 26963a10b..bc8a0ecb9 100644
--- a/packages/trueforge-sdk/tests/wire/skills.test.ts
+++ b/packages/trueforge-sdk/tests/wire/skills.test.ts
@@ -9,7 +9,7 @@ describe("SkillsClient", () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawResponseBody = { data: [{ description: "description", name: "name" }] };
+ const rawResponseBody = { data: [{ description: "description", metadata: { key: "value" }, name: "name" }] };
server.mockEndpoint().get("/api/v1/skills").respondWith().statusCode(200).jsonBody(rawResponseBody).build();
@@ -18,6 +18,9 @@ describe("SkillsClient", () => {
data: [
{
description: "description",
+ metadata: {
+ key: "value",
+ },
name: "name",
},
],
@@ -36,4 +39,56 @@ describe("SkillsClient", () => {
return await client.skills.list();
}).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
});
+
+ test("list_versions (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = {
+ data: [{ description: "description", display_name: "display_name", name: "name", version: 1 }],
+ };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/skills/versions")
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.skills.listVersions({
+ name: "name",
+ });
+ expect(response).toEqual({
+ data: [
+ {
+ description: "description",
+ displayName: "display_name",
+ name: "name",
+ version: 1,
+ },
+ ],
+ });
+ });
+
+ test("list_versions (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/skills/versions")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.skills.listVersions({
+ name: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
});
diff --git a/packages/trueforge-ui/src/atoms/draft/agentConfigMounts.ts b/packages/trueforge-ui/src/atoms/draft/agentConfigMounts.ts
index 882045da7..556858bcf 100644
--- a/packages/trueforge-ui/src/atoms/draft/agentConfigMounts.ts
+++ b/packages/trueforge-ui/src/atoms/draft/agentConfigMounts.ts
@@ -9,9 +9,9 @@ export function editableMountsFromSpec(value: unknown): EditableMount[] {
const mounts: EditableMount[] = [];
for (const item of value) {
if (typeof item !== 'object' || item === null) continue;
+ const displayNameRaw = Reflect.get(item, 'display_name');
const name = Reflect.get(item, 'name');
- const fqn = Reflect.get(item, 'fqn');
- const displayName = typeof name === 'string' ? name : typeof fqn === 'string' ? fqn : null;
+ const displayName = typeof displayNameRaw === 'string' ? displayNameRaw : typeof name === 'string' ? name : null;
if (displayName === null) continue;
const id = Reflect.get(item, 'id');
mounts.push({ id: typeof id === 'string' ? id : displayName, name: displayName, value: item });
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/builderServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/builderServer.ts
index b6b8adef4..c13860d2a 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/builderServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/builderServer.ts
@@ -83,9 +83,16 @@ export function createHarnessBuilderServer(
});
},
// Skills require a configured sandbox provider; keep the picker empty when skill capability is off.
+ // Catalog AvailableSkill.name is store identity (FQN in TFY). Picker `id` copies that
+ // attach key; `name` is displayName so the draft can show a label without losing the wire key.
+ // Draft mounts `{ id, name }`; toHarnessSkill admits AgentSpec.skills[].name = id ?? name.
getSkills: async () => {
const skills = await listSkills(client);
- return skills.map(skill => ({ id: skill.name, name: skill.name, description: skill.description }));
+ return skills.map(skill => ({
+ id: skill.name,
+ name: skill.metadata?.display_name ?? skill.name,
+ description: skill.description,
+ }));
},
getMcp: async () => (await listConfiguredMcpServers(client)).map(toUiConnectorFromReadEntry),
getMcpConnector: async ({ connectorId }: { connectorId: string }) => {
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/skillCatalog.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/skillCatalog.ts
index 9dd975c43..221ac7554 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/skillCatalog.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/skillCatalog.ts
@@ -23,7 +23,7 @@ export function toUiCatalogEntry(skill: TrueForgeApi.CatalogSkill): UiSkillCatal
};
}
-export function toHarnessManifest(req: SkillConfigBase): TrueForgeApi.SkillManifest {
+export function toHarnessManifest(req: SkillConfigBase): TrueForgeApi.settings.CreateSkillRequest['manifest'] {
const path = req.path.trim();
return {
type: 'git',
@@ -36,10 +36,13 @@ export function toHarnessManifest(req: SkillConfigBase): TrueForgeApi.SkillManif
}
export function toUiSkill(skill: TrueForgeApi.ConfiguredSkill, catalogNames: ReadonlySet<string>): UiSkill {
+ const manifest = skill.manifest;
+ const displayName =
+ 'displayName' in manifest && typeof manifest.displayName === 'string' ? manifest.displayName : manifest.name;
const base = {
id: skill.name,
- name: skill.name,
- description: skill.manifest.description,
+ name: displayName,
+ description: manifest.description,
};
if (catalogNames.has(skill.name)) {
return { ...base, catalogId: skill.name };
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
index aa231ec77..7c0d50c6c 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
@@ -5,7 +5,7 @@
* `nextPageToken`), and `null` normalized to absent. Harness keys MCP mounts by
* name and returns `null` for optional fields — the maps below bridge both.
*
- * Skills are name refs on the wire (`Skill`).
+ * Skills are name (+ optional preload) refs on the wire (`Skill`).
*
* Session create takes `{ name }` or `{ spec }`; reads carry the
* `reference`/`inline` discriminator, with reference rows already naming their
@@ -44,7 +44,12 @@ function toUiMcpServer(server: TrueForgeApi.McpServer): HarnessMcpServerMount {
}
function toUiSkill(skill: TrueForgeApi.Skill): HarnessSkillMount {
- return { name: skill.name };
+ return { name: skill.name, preload: skill.preload === true };
+}
+
+function toHarnessSkill(skill: HarnessSkillMount): TrueForgeApi.Skill {
+ // Picker `id` is AvailableSkill.name (attach key); `name` is display — see builder getSkills.
+ return { name: skill.id ?? skill.name, preload: skill.preload === true };
}
/** Drop UI draft `id` before admission; Harness MCP mounts are name-keyed. */
@@ -65,7 +70,7 @@ export function toHarnessAgentSpec(spec: HarnessAgentSpec): TrueForgeApi.AgentSp
return server;
}),
}),
- ...(skills === undefined ? {} : { skills: skills.map(({ name }) => ({ name })) }),
+ ...(skills === undefined ? {} : { skills: skills.map(toHarnessSkill) }),
};
}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts
index 10b2a8200..c97cf0744 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/types.ts
@@ -1,10 +1,11 @@
import type { TrueForgeApi } from '@truefoundry/trueforge-sdk';
import type { AgentSpec } from '../../server/types.js';
-export type HarnessSkillMount = TrueForgeApi.Skill;
+/** Catalog attach key may sit on `id`; wire Skill is name-only. See builder getSkills. */
+export type HarnessSkillMount = TrueForgeApi.Skill & { id?: string };
export type HarnessMcpServerMount = TrueForgeApi.McpServer;
export interface HarnessAgentSpec
extends
AgentSpec<TrueForgeApi.Model, HarnessSkillMount, HarnessMcpServerMount, TrueForgeApi.RuntimeConfig>,
- TrueForgeApi.AgentSpec {}
+ Omit<TrueForgeApi.AgentSpec, 'skills'> {}
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessBuilderServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessBuilderServer.test.ts
index fe5399138..1b4a76ce2 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessBuilderServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessBuilderServer.test.ts
@@ -267,7 +267,7 @@ describe('harnessBuilderServer', () => {
agentSpec: {
model: { name: 'test/model' },
instructions: 'Review carefully.',
- skills: [{ name: 'review' }],
+ skills: [{ name: 'review', preload: false }],
mcpServers: [{ name: 'github', enableTools: ['@all'] }],
},
});
@@ -312,7 +312,7 @@ describe('harnessBuilderServer', () => {
name: 'saved-agent',
manifest: {
model: { name: 'test/model' },
- skills: [{ name: 'review' }],
+ skills: [{ name: 'review', preload: false }],
},
});
});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts
index b82b34117..b7561dc64 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts
@@ -1,7 +1,12 @@
import assert from 'node:assert/strict';
import { describe, it } from 'vitest';
-import { createHarnessChatServer, type HarnessAgentSpec } from '@/plugins/trueforge-agent-server-adapter/chatServer.js';
+import {
+ createHarnessChatServer,
+ toHarnessAgentSpec,
+ toUiAgentSpec,
+ type HarnessAgentSpec,
+} from '@/plugins/trueforge-agent-server-adapter/chatServer.js';
const session = {
id: 'ses_1',
@@ -75,17 +80,17 @@ describe('createHarnessChatServer', () => {
assert.equal(created.isMutable, true);
assert.equal(created.title, undefined);
assert.deepEqual(created.agentSpec?.mcpServers?.[0], { name: 'github', enableTools: ['@all'] });
- assert.deepEqual(created.agentSpec?.skills?.[0], { name: 'review' });
+ assert.deepEqual(created.agentSpec?.skills?.[0], { name: 'review', preload: false });
});
it('sends skill name refs and strips UI-only mount ids before admission', async () => {
const server = createHarnessChatServer({ fetch: fetchMock });
+ const skillName = 'agent-skill:acme/team-a/echo:3';
await server.createSession({
agentSpec: {
model: { name: 'test/model' },
- // Draft picker may round-trip a mount as `{ id, name }`.
- skills: [{ name: 'review' }],
+ skills: [{ id: skillName, name: 'echo', preload: true }],
mcpServers: [{ name: 'github', enableTools: ['@all'] }],
},
});
@@ -96,11 +101,23 @@ describe('createHarnessChatServer', () => {
spec: {
model: { name: 'test/model' },
mcp_servers: [{ name: 'github', enable_tools: ['@all'] }],
- skills: [{ name: 'review' }],
+ skills: [{ name: skillName, preload: true }],
},
});
});
+ it('defaults skill preload to false when omitted', () => {
+ const ui = toUiAgentSpec({
+ model: { name: 'test/model' },
+ skills: [{ name: 'agent-skill:acme/team-a/echo:3' }],
+ });
+ assert.deepEqual(ui.skills?.[0], { name: 'agent-skill:acme/team-a/echo:3', preload: false });
+ assert.deepEqual(toHarnessAgentSpec({ model: { name: 'test/model' }, skills: [{ name: 'echo' }] }).skills?.[0], {
+ name: 'echo',
+ preload: false,
+ });
+ });
+
it('reports pages under the ListResult pagination contract', async () => {
const server = createHarnessChatServer({ fetch: fetchMock });
diff --git a/packages/trueforge/scripts/write-openapi.ts b/packages/trueforge/scripts/write-openapi.ts
index 9bbdd0a3b..c28cb1afe 100644
--- a/packages/trueforge/scripts/write-openapi.ts
+++ b/packages/trueforge/scripts/write-openapi.ts
@@ -62,6 +62,7 @@ const sessionStore = new InMemorySessionStore();
const db = createSqliteDb(':memory:');
const tokenStore = new SqliteOAuthTokenStore(db);
const agentStore = new SqliteAgentStore(db);
+const skillStore = new SqliteSkillStore(db);
const app = createServerApp({
modelCatalog: ModelCatalog.load(),
resolveModelProviderStore: () => new SqliteModelProviderStore(db),
@@ -75,7 +76,7 @@ const app = createServerApp({
}),
tokenStore,
skillCatalog: SkillCatalog.load(),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => skillStore,
sandboxCatalog: SandboxCatalog.load(),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
resolveAgentStore: () => agentStore,
diff --git a/packages/trueforge/src/apis/agents.ts b/packages/trueforge/src/apis/agents.ts
index 3661d7747..df7c611d0 100644
--- a/packages/trueforge/src/apis/agents.ts
+++ b/packages/trueforge/src/apis/agents.ts
@@ -29,12 +29,13 @@ import { validateAgentSpec } from '../runtime/sessionResources';
import { type Agent, type CreateAgentRequest } from '../schemas/agent';
import { agentIfAccessible, listAccessibleAgents } from './agentAccess';
import { buildAgentCodeSnippets } from './agentCodeSnippets';
+import type { ResolveSkillStore } from './skills';
export interface AgentsRouterDeps<TTransaction> {
resolveAgentStore: (c: Context) => IAgentStore<TTransaction>;
resolveModelProviderStore: (c: Context) => IModelProviderStore<TTransaction>;
resolveMcpServerStore: (c: Context) => IMcpServerStore<TTransaction>;
- skillStore: ISkillStore<TTransaction>;
+ resolveSkillStore: ResolveSkillStore<TTransaction>;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
resolveRequestContext: ResolveRequestContext;
@@ -53,16 +54,16 @@ function toWireAgent(record: AgentRecord): Agent {
async function validateManifest<TTransaction>({
spec,
- deps,
modelProviderStore,
mcpServerStore,
+ skillStore,
sandboxProviderStore,
tenant_id,
}: {
spec: AgentSpec;
- deps: AgentsRouterDeps<TTransaction>;
modelProviderStore: IModelProviderStore<TTransaction>;
mcpServerStore: IMcpServerStore<TTransaction>;
+ skillStore: ISkillStore<TTransaction>;
sandboxProviderStore: ISandboxProviderStore<TTransaction>;
tenant_id: string;
}): Promise<AgentSpec> {
@@ -71,7 +72,7 @@ async function validateManifest<TTransaction>({
tenant_id,
modelProviderStore,
mcpServerStore,
- skillStore: deps.skillStore,
+ skillStore,
sandboxProviderStore,
});
return spec;
@@ -94,9 +95,9 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
const requestContext = deps.resolveRequestContext(c);
const manifest = await validateManifest({
spec: body.manifest,
- deps,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
+ skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
tenant_id: requestContext.tenant_id,
});
@@ -186,9 +187,9 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
}
const manifest = await validateManifest({
spec: body.manifest,
- deps,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
+ skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
tenant_id: requestContext.tenant_id,
});
diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.ts
index c4043c152..5e275a30f 100644
--- a/packages/trueforge/src/apis/sessions.ts
+++ b/packages/trueforge/src/apis/sessions.ts
@@ -28,7 +28,6 @@ import type { IAgentStore } from '../db/agentStore';
import type { IMcpServerStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
-import type { ISkillStore } from '../db/skillStore';
import {
cancelSessionRoute,
createSessionRoute,
@@ -46,6 +45,7 @@ import { honoQueriesToRecord } from '../schemas/deepObjectQuery';
import { isSessionAgentNameRef, parseListSessionsQuery, type Session } from '../schemas/session';
import { newId } from '../utils/id';
import { agentIfAccessible, canReadAgentBoundResource, resolveManagedAgentIds } from './agentAccess';
+import type { ResolveSkillStore } from './skills';
/** Request-reply path a replica serves to cancel a turn it owns. */
export const SESSIONS_CANCEL_PATH = 'sessions/cancel';
@@ -78,7 +78,7 @@ export interface SessionsRouterDeps {
activeTurns: ActiveTurnRegistry;
resolveModelProviderStore: (c: Context) => IModelProviderStore;
resolveMcpServerStore: (c: Context) => IMcpServerStore;
- skillStore: ISkillStore;
+ resolveSkillStore: ResolveSkillStore;
resolveAgentStore: (c: Context) => IAgentStore;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore;
redis?: RedisClientType | undefined;
@@ -234,7 +234,7 @@ type InternalSessionsRouterDeps = Pick<
| 'sessions'
| 'resolveModelProviderStore'
| 'resolveMcpServerStore'
- | 'skillStore'
+ | 'resolveSkillStore'
| 'resolveAgentStore'
| 'resolveSandboxProviderStore'
| 'resolveRequestContext'
@@ -288,7 +288,7 @@ function createGetOrCreateSessionByExternalIdHandler(
tenant_id: requestContext.tenant_id,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
- skillStore: deps.skillStore,
+ skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
});
agent = { type: 'inline', spec: body.agent.spec };
@@ -360,7 +360,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
tenant_id: requestContext.tenant_id,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
- skillStore: deps.skillStore,
+ skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
});
const session = await deps.sessions.create({
@@ -451,7 +451,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
tenant_id: requestContext.tenant_id,
modelProviderStore: deps.resolveModelProviderStore(c),
mcpServerStore: deps.resolveMcpServerStore(c),
- skillStore: deps.skillStore,
+ skillStore: deps.resolveSkillStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
});
}
diff --git a/packages/trueforge/src/apis/settings.ts b/packages/trueforge/src/apis/settings.ts
index f9133d130..783da8d36 100644
--- a/packages/trueforge/src/apis/settings.ts
+++ b/packages/trueforge/src/apis/settings.ts
@@ -10,19 +10,18 @@ import type { ResolveRequestContext } from '../auth/identity';
import type { IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
-import type { ISkillStore } from '../db/skillStore';
import type { WithTransaction } from '../db/transaction';
import type { IOAuthTokenStore } from '../mcp/auth/types';
import { createSettingsMcpServersRouter } from './mcpServers';
import { createModelProvidersRouter } from './modelProviders';
import { createSandboxProvidersRouter } from './sandboxProviders';
-import { createSkillsRouter } from './skills';
+import { createSkillsRouter, type ResolveSkillStore } from './skills';
export interface SettingsRouterDeps<TTransaction> {
resolveModelProviderStore: (c: Context) => IModelProviderStore<TTransaction>;
resolveMcpServerStore: (c: Context) => IMcpServerWithAuthStore<TTransaction>;
tokenStore: IOAuthTokenStore<TTransaction>;
- skillStore: ISkillStore<TTransaction>;
+ resolveSkillStore: ResolveSkillStore<TTransaction>;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
logger: Logger;
@@ -52,7 +51,7 @@ export function createSettingsRouter<TTransaction>(deps: SettingsRouterDeps<TTra
router.route(
'/skills',
createSkillsRouter({
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
withTransaction: deps.withTransaction,
resolveRequestContext: deps.resolveRequestContext,
}),
diff --git a/packages/trueforge/src/apis/skills.ts b/packages/trueforge/src/apis/skills.ts
index da729377d..bffce948f 100644
--- a/packages/trueforge/src/apis/skills.ts
+++ b/packages/trueforge/src/apis/skills.ts
@@ -1,22 +1,30 @@
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
+import type { Context } from 'hono';
import type { ResolveRequestContext } from '../auth/identity';
+import type { AgentRecord } from '../db/agentStore';
import { SkillNameConflictError, type ISkillStore, type SkillRecord } from '../db/skillStore';
import type { WithTransaction } from '../db/transaction';
import {
createSkillRoute,
listAvailableSkillsRoute,
listConfiguredSkillsRoute,
+ listSkillVersionsRoute,
putSkillRoute,
} from '../routes/skillRoutes';
-import type { ConfiguredSkill, CreateSkillRequest, UpdateSkillRequest } from '../schemas/skill';
+import type { AvailableSkill, ConfiguredSkill, CreateSkillRequest, UpdateSkillRequest } from '../schemas/skill';
+import { parseTrueFoundryRegistrySkill } from '../schemas/skill';
+
+export type ResolveSkillStore<TTransaction = never> = (
+ c: Context,
+ runAsAgent?: AgentRecord,
+) => ISkillStore<TTransaction>;
export interface SkillsRouterDeps<TTransaction> {
- skillStore: ISkillStore<TTransaction>;
+ resolveSkillStore: ResolveSkillStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
resolveRequestContext: ResolveRequestContext;
}
-/** Wire view of a stored skill: identity `name` plus nested manifest. */
function toConfiguredSkill(record: SkillRecord): ConfiguredSkill {
return {
name: record.name,
@@ -24,11 +32,28 @@ function toConfiguredSkill(record: SkillRecord): ConfiguredSkill {
};
}
+function toAvailableSkill(record: SkillRecord): AvailableSkill {
+ const { manifest } = record;
+ const registry = parseTrueFoundryRegistrySkill(manifest);
+ if (registry !== undefined) {
+ return {
+ name: record.name,
+ description: registry.description,
+ metadata: {
+ display_name: registry.display_name,
+ repository_name: registry.repository_name,
+ version: String(registry.version),
+ },
+ };
+ }
+ return { name: record.name, description: manifest.description };
+}
+
/** Admin/settings skills CRUD (mounted at /api/v1/settings/skills). */
export function createSkillsRouter<TTransaction>(deps: SkillsRouterDeps<TTransaction>) {
const listConfiguredHandler: RouteHandler<typeof listConfiguredSkillsRoute> = async c => {
const requestContext = deps.resolveRequestContext(c);
- const records = await deps.skillStore.listSkills({
+ const records = await deps.resolveSkillStore(c).listSkills({
tenant_id: requestContext.tenant_id,
names: undefined,
});
@@ -38,9 +63,9 @@ export function createSkillsRouter<TTransaction>(deps: SkillsRouterDeps<TTransac
const createHandler: RouteHandler<typeof createSkillRoute> = async c => {
const body: CreateSkillRequest = c.req.valid('json');
const requestContext = deps.resolveRequestContext(c);
- const manifest = body.manifest;
+ const { manifest } = body;
try {
- const record = await deps.skillStore.createSkill({
+ const record = await deps.resolveSkillStore(c).createSkill({
tenant_id: requestContext.tenant_id,
name: manifest.name,
manifest,
@@ -57,8 +82,8 @@ export function createSkillsRouter<TTransaction>(deps: SkillsRouterDeps<TTransac
const putHandler: RouteHandler<typeof putSkillRoute> = async c => {
const body: UpdateSkillRequest = c.req.valid('json');
const requestContext = deps.resolveRequestContext(c);
- const manifest = body.manifest;
- const record = await deps.skillStore.upsertSkill({
+ const { manifest } = body;
+ const record = await deps.resolveSkillStore(c).upsertSkill({
tenant_id: requestContext.tenant_id,
name: manifest.name,
manifest,
@@ -73,28 +98,22 @@ export function createSkillsRouter<TTransaction>(deps: SkillsRouterDeps<TTransac
return router;
}
-/** Chat slim list (mounted at /api/v1/skills) — mirrors GET /api/v1/mcp-servers. */
-export function createAvailableSkillsRouter<TTransaction>(deps: {
- skillStore: ISkillStore<TTransaction>;
- withTransaction: WithTransaction<TTransaction>;
- resolveRequestContext: ResolveRequestContext;
-}) {
+/** Chat slim list (mounted at /api/v1/skills). */
+export function createAvailableSkillsRouter<TTransaction>(deps: SkillsRouterDeps<TTransaction>) {
const router = new OpenAPIHono();
router.openapi(listAvailableSkillsRoute, async c => {
const requestContext = deps.resolveRequestContext(c);
- const records = await deps.skillStore.listSkills({
+ const records = await deps.resolveSkillStore(c).listSkills({
tenant_id: requestContext.tenant_id,
names: undefined,
});
- return c.json(
- {
- data: records.map(record => ({
- name: record.name,
- description: record.manifest.description,
- })),
- },
- 200,
- );
+ return c.json({ data: records.map(toAvailableSkill) }, 200);
});
+
+ router.openapi(listSkillVersionsRoute, async c => {
+ const { name } = c.req.valid('query');
+ return c.json({ data: await deps.resolveSkillStore(c).listSkillVersions({ name }) }, 200);
+ });
+
return router;
}
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index d17931b06..86cecde24 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -107,7 +107,7 @@ export interface TurnsRouterDeps {
activeTurns: ActiveTurnRegistry;
resolveModelProviderStore: (c: Context, runAsAgent?: AgentRecord) => IModelProviderStore;
resolveMcpServerStore: (c: Context, runAsAgent?: AgentRecord) => IMcpServerWithAuthStore;
- skillStore: ISkillStore;
+ resolveSkillStore: (c: Context, runAsAgent?: AgentRecord) => ISkillStore;
resolveAgentStore: (c: Context) => IAgentStore;
/** Resumable live turn-event transport: create-turn writes, subscribe polls. */
eventSubscriptions: EventSubscriptionRegistry<TurnStreamingEvent>;
@@ -119,14 +119,11 @@ export interface TurnsRouterDeps {
/**
* Deps needed to create a turn and drain events in-process (no HTTP). Carries already-resolved
- * `modelProviderStore` / `mcpServerStore` / `agentStore` / `sandboxProviderStore`; callers must
- * resolve them from the request context (e.g. schedule `resolveTurnDeps(c)`) so TrueFoundry mode
- * stays token-bound.
+ * stores; callers must resolve them from the request context (e.g. schedule `resolveTurnDeps(c, agent)`)
+ * so TrueFoundry mode stays token-bound for models, MCP, and skills.
*/
-export type BeginTurnExecutionDeps = Pick<
- TurnsRouterDeps,
- 'activeTurns' | 'eventSubscriptions' | 'skillStore' | 'logger'
-> & {
+export type BeginTurnExecutionDeps = Pick<TurnsRouterDeps, 'activeTurns' | 'eventSubscriptions' | 'logger'> & {
+ skillStore: ISkillStore;
modelProviderStore: IModelProviderStore;
mcpServerStore: IMcpServerWithAuthStore;
agentStore: IAgentStore;
@@ -757,6 +754,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
...deps,
modelProviderStore: deps.resolveModelProviderStore(c, referencedAgent),
mcpServerStore: deps.resolveMcpServerStore(c, referencedAgent),
+ skillStore: deps.resolveSkillStore(c, referencedAgent),
agentStore: deps.resolveAgentStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
},
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index dc2c5afb2..1d421f6c8 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -21,7 +21,7 @@ import { createSchedulesRouter } from './apis/schedules';
import { createInternalMetricsRouter } from './apis/sessionMetrics';
import { createInternalSessionsRouter, createSessionsRouter } from './apis/sessions';
import { createSettingsRouter } from './apis/settings';
-import { createAvailableSkillsRouter } from './apis/skills';
+import { createAvailableSkillsRouter, type ResolveSkillStore } from './apis/skills';
import { createTurnsRouter } from './apis/turns';
import type { Authenticator } from './auth/authenticator';
import type { Authorizer } from './auth/authorizer';
@@ -38,7 +38,6 @@ import type { IModelProviderStore } from './db/modelProviderStore';
import type { ISandboxProviderStore } from './db/sandboxProviderStore';
import type { IScheduleStore } from './db/scheduleStore';
import type { ISessionMetricsStore } from './db/sessionMetricsStore';
-import type { ISkillStore } from './db/skillStore';
import type { WithTransaction } from './db/transaction';
import { createClientCertificateMiddleware } from './http/tls';
import type { IOAuthTokenStore } from './mcp/auth/types';
@@ -185,7 +184,6 @@ export interface ServerDeps<TTransaction> {
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
tokenStore: IOAuthTokenStore<TTransaction>;
- skillStore: ISkillStore<TTransaction>;
scheduleStore: IScheduleStore<TTransaction>;
sessionStore: ISessionStore;
sessionMetricsStore: ISessionMetricsStore;
@@ -204,6 +202,8 @@ export interface ServerDeps<TTransaction> {
authenticator: Authenticator;
/** Startup-selected agent authorization policy. */
authorizer: Authorizer;
+ /** Per-request store: DB git skills, or SFY registry catalog in TrueFoundry mode. */
+ resolveSkillStore: ResolveSkillStore<TTransaction>;
}
export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
@@ -292,7 +292,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
'/api/v1/skills',
withAuth(
createAvailableSkillsRouter({
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
withTransaction: deps.withTransaction,
resolveRequestContext,
}),
@@ -306,7 +306,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveAgentStore: deps.resolveAgentStore,
resolveModelProviderStore: deps.resolveModelProviderStore,
resolveMcpServerStore: deps.resolveMcpServerStore,
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
withTransaction: deps.withTransaction,
resolveRequestContext,
@@ -327,7 +327,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
eventSubscriptions: deps.eventSubscriptions,
modelProviderStore: deps.resolveModelProviderStore(c, runAsAgent),
mcpServerStore: deps.resolveMcpServerStore(c, runAsAgent),
- skillStore: deps.skillStore,
+ skillStore: deps.resolveSkillStore(c, runAsAgent),
agentStore: deps.resolveAgentStore(c),
sandboxProviderStore: deps.resolveSandboxProviderStore(c),
logger: deps.logger,
@@ -346,7 +346,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
resolveModelProviderStore: deps.resolveModelProviderStore,
resolveMcpServerStore: deps.resolveMcpServerStore,
tokenStore: deps.tokenStore,
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
withTransaction: deps.withTransaction,
logger: deps.logger,
@@ -362,7 +362,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
sessions: deps.sessions,
resolveModelProviderStore: deps.resolveModelProviderStore,
resolveMcpServerStore: deps.resolveMcpServerStore,
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
resolveAgentStore: deps.resolveAgentStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
resolveRequestContext,
@@ -392,7 +392,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
activeTurns: deps.activeTurns,
resolveModelProviderStore: deps.resolveModelProviderStore,
resolveMcpServerStore: deps.resolveMcpServerStore,
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
resolveAgentStore: deps.resolveAgentStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
redis: deps.redis,
@@ -413,7 +413,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
activeTurns: deps.activeTurns,
resolveModelProviderStore: deps.resolveModelProviderStore,
resolveMcpServerStore: deps.resolveMcpServerStore,
- skillStore: deps.skillStore,
+ resolveSkillStore: deps.resolveSkillStore,
resolveAgentStore: deps.resolveAgentStore,
eventSubscriptions: deps.eventSubscriptions,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
diff --git a/packages/trueforge/src/db/gitSkillMounts.ts b/packages/trueforge/src/db/gitSkillMounts.ts
new file mode 100644
index 000000000..ef167cde7
--- /dev/null
+++ b/packages/trueforge/src/db/gitSkillMounts.ts
@@ -0,0 +1,35 @@
+import { HTTPException } from 'hono/http-exception';
+import type { AgentSkillsInput, ISkillStore } from './skillStore';
+
+/** Admit configured git skills; reject preload. */
+export async function validateGitAgentSkills(
+ store: Pick<ISkillStore, 'listSkills'>,
+ input: AgentSkillsInput,
+): Promise<void> {
+ const { tenant_id, skills } = input;
+ if (skills.length === 0) {
+ return;
+ }
+ for (const skill of skills) {
+ if (skill.preload) {
+ throw new HTTPException(422, {
+ message: `Skill "${skill.name}": preload is not supported for git skills`,
+ });
+ }
+ }
+ const names = skills.map(skill => skill.name);
+ const byName = new Map((await store.listSkills({ tenant_id, names })).map(record => [record.name, record]));
+ for (const skill of skills) {
+ const record = byName.get(skill.name);
+ if (record === undefined) {
+ throw new HTTPException(422, {
+ message: `Unknown skill "${skill.name}" — not configured`,
+ });
+ }
+ if (record.manifest.type !== 'git') {
+ throw new HTTPException(422, {
+ message: `Skill "${skill.name}" is not a git skill`,
+ });
+ }
+ }
+}
diff --git a/packages/trueforge/src/db/postgres/skill-store/PostgresSkillStore.ts b/packages/trueforge/src/db/postgres/skill-store/PostgresSkillStore.ts
index 02ee203fc..cbd8b17bd 100644
--- a/packages/trueforge/src/db/postgres/skill-store/PostgresSkillStore.ts
+++ b/packages/trueforge/src/db/postgres/skill-store/PostgresSkillStore.ts
@@ -1,8 +1,10 @@
import type { Kysely, Selectable, Transaction } from 'kysely';
+import type { SkillVersion } from '../../../schemas/skill';
+import { validateGitAgentSkills } from '../../gitSkillMounts';
import {
SkillNameConflictError,
+ type AgentSkillsInput,
type CreateSkillInput,
- type GetSkillInput,
type ISkillStore,
type ListSkillsInput,
type SkillRecord,
@@ -42,17 +44,6 @@ export class PostgresSkillStore implements ISkillStore<Transaction<Database>> {
return rows.map(toRecord);
}
- async getSkill(input: GetSkillInput, transaction?: Transaction<Database>): Promise<SkillRecord | undefined> {
- const db = transaction ?? this.#db;
- const row = await db
- .selectFrom('skill')
- .selectAll()
- .where('tenant_id', '=', input.tenant_id)
- .where('name', '=', input.name)
- .executeTakeFirst();
- return row === undefined ? undefined : toRecord(row);
- }
-
async createSkill(input: CreateSkillInput, transaction?: Transaction<Database>): Promise<SkillRecord> {
const db = transaction ?? this.#db;
try {
@@ -97,4 +88,14 @@ export class PostgresSkillStore implements ISkillStore<Transaction<Database>> {
.executeTakeFirstOrThrow();
return toRecord(row);
}
+
+ listSkillVersions(input: { name: string }): Promise<SkillVersion[]> {
+ void input;
+ return Promise.resolve([]);
+ }
+
+ validateAgentSkills(input: AgentSkillsInput, transaction?: Transaction<Database>): Promise<void> {
+ void transaction;
+ return validateGitAgentSkills(this, input);
+ }
}
diff --git a/packages/trueforge/src/db/skillStore.ts b/packages/trueforge/src/db/skillStore.ts
index 312ec14a7..22ef027fa 100644
--- a/packages/trueforge/src/db/skillStore.ts
+++ b/packages/trueforge/src/db/skillStore.ts
@@ -3,12 +3,16 @@
* identity as columns plus a Zod-validated `SkillManifest` jsonb document.
* Implementations: PostgresSkillStore and SqliteSkillStore.
*/
-import type { ResourceName } from '../schemas/common';
-import type { SkillManifest } from '../schemas/skill';
+import type { Skill as AgentSkillRef } from '@truefoundry/trueforge-core/agent-session';
+import type { SkillManifest, SkillVersion } from '../schemas/skill';
export interface SkillRecord {
tenant_id: string;
- name: ResourceName;
+ /**
+ * Store identity: git ResourceName in standalone, registry version FQN in TrueFoundry.
+ * Same string as AgentSpec `skills[].name`, list filters, and AvailableSkill `name`.
+ */
+ name: string;
manifest: SkillManifest;
/** ISO-8601 UTC instant. */
created_at: string;
@@ -16,11 +20,6 @@ export interface SkillRecord {
updated_at: string;
}
-export interface GetSkillInput {
- tenant_id: string;
- name: string;
-}
-
export interface ListSkillsInput {
tenant_id: string;
/** `undefined` lists all; empty returns `[]` without querying; otherwise `WHERE name IN (...)`. */
@@ -29,13 +28,19 @@ export interface ListSkillsInput {
export interface CreateSkillInput {
tenant_id: string;
- name: ResourceName;
+ name: string;
manifest: SkillManifest;
}
/** Same shape as create for now; kept as a distinct name for the upsert path. */
export type UpsertSkillInput = CreateSkillInput;
+/** AgentSpec `skills` refs for save validate. */
+export interface AgentSkillsInput {
+ tenant_id: string;
+ skills: readonly AgentSkillRef[];
+}
+
/** Unique `(tenant_id, name)` violation on create. */
export class SkillNameConflictError extends Error {
readonly tenant_id: string;
@@ -51,9 +56,11 @@ export class SkillNameConflictError extends Error {
export interface ISkillStore<TTransaction = never> {
listSkills(input: ListSkillsInput, transaction?: TTransaction): Promise<SkillRecord[]>;
- getSkill(input: GetSkillInput, transaction?: TTransaction): Promise<SkillRecord | undefined>;
/** Inserts a new skill. Throws SkillNameConflictError on name clash. */
createSkill(input: CreateSkillInput, transaction?: TTransaction): Promise<SkillRecord>;
/** Single-row write: creates the skill or replaces the whole manifest. */
upsertSkill(input: UpsertSkillInput, transaction?: TTransaction): Promise<SkillRecord>;
+ listSkillVersions(input: { name: string }): Promise<SkillVersion[]>;
+ /** Admit AgentSpec skill refs (git store or TrueFoundry SFY resolve with caller token). */
+ validateAgentSkills(input: AgentSkillsInput, transaction?: TTransaction): Promise<void>;
}
diff --git a/packages/trueforge/src/db/sqlite/skill-store/SqliteSkillStore.ts b/packages/trueforge/src/db/sqlite/skill-store/SqliteSkillStore.ts
index c82b593a8..c4bc2ca56 100644
--- a/packages/trueforge/src/db/sqlite/skill-store/SqliteSkillStore.ts
+++ b/packages/trueforge/src/db/sqlite/skill-store/SqliteSkillStore.ts
@@ -1,9 +1,10 @@
import type { ExpressionBuilder, Kysely, Transaction } from 'kysely';
-import type { SkillManifest } from '../../../schemas/skill';
+import type { SkillManifest, SkillVersion } from '../../../schemas/skill';
+import { validateGitAgentSkills } from '../../gitSkillMounts';
import {
SkillNameConflictError,
+ type AgentSkillsInput,
type CreateSkillInput,
- type GetSkillInput,
type ISkillStore,
type ListSkillsInput,
type SkillRecord,
@@ -43,16 +44,6 @@ export class SqliteSkillStore implements ISkillStore<Transaction<Database>> {
return await query.orderBy('name').execute();
}
- async getSkill(input: GetSkillInput, transaction?: Transaction<Database>): Promise<SkillRecord | undefined> {
- const db = transaction ?? this.#db;
- return await db
- .selectFrom('skill')
- .select(recordColumns)
- .where('tenant_id', '=', input.tenant_id)
- .where('name', '=', input.name)
- .executeTakeFirst();
- }
-
async createSkill(input: CreateSkillInput, transaction?: Transaction<Database>): Promise<SkillRecord> {
const db = transaction ?? this.#db;
const timestamp = nowIso();
@@ -97,4 +88,14 @@ export class SqliteSkillStore implements ISkillStore<Transaction<Database>> {
.returning(recordColumns)
.executeTakeFirstOrThrow();
}
+
+ listSkillVersions(input: { name: string }): Promise<SkillVersion[]> {
+ void input;
+ return Promise.resolve([]);
+ }
+
+ validateAgentSkills(input: AgentSkillsInput, transaction?: Transaction<Database>): Promise<void> {
+ void transaction;
+ return validateGitAgentSkills(this, input);
+ }
}
diff --git a/packages/trueforge/src/main.ts b/packages/trueforge/src/main.ts
index fc8ef6e48..f105cbf99 100644
--- a/packages/trueforge/src/main.ts
+++ b/packages/trueforge/src/main.ts
@@ -56,6 +56,7 @@ import type { Kysely, Transaction } from 'kysely';
import type { RedisClientType } from 'redis';
import type { Logger } from 'winston';
+import type { ResolveSkillStore } from './apis/skills';
import { createServerApp } from './app';
import { TrueForgeAuthorizer, type Authorizer } from './auth/authorizer';
import { createAuthenticator } from './auth/createAuthenticator';
@@ -94,6 +95,7 @@ import { TrueFoundryMcpServerStore } from './truefoundry/TrueFoundryMcpServerSto
import { TrueFoundryModelProviderStore } from './truefoundry/TrueFoundryModelProviderStore';
import { TrueFoundrySandboxProviderStore } from './truefoundry/TrueFoundrySandboxProviderStore';
import { TrueFoundryServiceFoundryServerClient } from './truefoundry/TrueFoundryServiceFoundryServerClient';
+import { TrueFoundrySkillStore } from './truefoundry/TrueFoundrySkillStore';
/** Persistence + optional Redis wired for the selected topology. */
interface ServerPersistence<TTransaction> {
@@ -105,12 +107,13 @@ interface ServerPersistence<TTransaction> {
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
tokenStore: IOAuthTokenStore<TTransaction>;
- skillStore: ISkillStore<TTransaction>;
scheduleStore: IScheduleStore<TTransaction>;
destroyDb: () => Promise<void>;
redis: RedisClientType | undefined;
/** One shared client for TrueFoundry store resolvers + auth; undefined when TrueFoundry mode is off. */
serviceFoundryClient: TrueFoundryServiceFoundryServerClient | undefined;
+ /** Per-request store: DB git skills, or SFY registry catalog in TrueFoundry mode. */
+ resolveSkillStore: ResolveSkillStore<TTransaction>;
}
/** Shared ServiceFoundry HTTP client when TrueFoundry mode is on; otherwise undefined. */
@@ -134,6 +137,27 @@ function createServiceFoundryServerClient(logger: Logger): TrueFoundryServiceFou
});
}
+/** Per-request SFY skill catalog; otherwise {@link persistenceStore}.
+ * `runAsAgent` is set only when a turn should use a saved agent's token.
+ */
+function buildResolveSkillStore<TTransaction>(options: {
+ persistenceStore: ISkillStore<TTransaction>;
+ client: TrueFoundryServiceFoundryServerClient | undefined;
+ logger: Logger;
+}): ResolveSkillStore<TTransaction> {
+ const { persistenceStore, client, logger } = options;
+ if (client === undefined) {
+ return () => persistenceStore;
+ }
+ return (c, runAsAgent) =>
+ new TrueFoundrySkillStore<TTransaction>({
+ client,
+ context: resolveRequestContext(c),
+ agent: runAsAgent,
+ logger,
+ });
+}
+
/**
* Per-request model-provider store over a shared ServiceFoundry client, else {@link persistenceStore}.
* `runAsAgent` is set only when a turn should use a saved agent's token.
@@ -273,6 +297,7 @@ async function createStandalonePersistence(options: {
clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
});
const sandboxProviderStore = new SqliteSandboxProviderStore(db);
+ const skillStore = new SqliteSkillStore(db);
return {
sessionStore: new SqliteSessionStore(db),
sessionMetricsStore: new SqliteSessionMetricsStore(db),
@@ -282,11 +307,11 @@ async function createStandalonePersistence(options: {
resolveSandboxProviderStore: () => sandboxProviderStore,
withTransaction: callback => db.transaction().execute(callback),
tokenStore,
- skillStore: new SqliteSkillStore(db),
scheduleStore: new SqliteScheduleStore(db),
destroyDb: () => db.destroy(),
redis: undefined,
serviceFoundryClient: undefined,
+ resolveSkillStore: () => skillStore,
};
}
@@ -367,6 +392,7 @@ async function createDistributedPersistence(options: {
const resolveSandboxProviderStore = buildResolveSandboxProviderStore({
persistenceStore: new PostgresSandboxProviderStore(db),
});
+ const skillStore = new PostgresSkillStore(db);
return {
sessionStore: new PostgresSessionStore(db),
sessionMetricsStore: new PostgresSessionMetricsStore(db),
@@ -376,11 +402,15 @@ async function createDistributedPersistence(options: {
resolveSandboxProviderStore,
withTransaction: callback => db.transaction().execute(callback),
tokenStore,
- skillStore: new PostgresSkillStore(db),
scheduleStore: new PostgresScheduleStore(db),
destroyDb: () => db.destroy(),
redis: await connectRedis({ url: redisUrl, logger }),
serviceFoundryClient,
+ resolveSkillStore: buildResolveSkillStore({
+ persistenceStore: skillStore,
+ client: serviceFoundryClient,
+ logger,
+ }),
};
}
@@ -395,11 +425,11 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
resolveSandboxProviderStore,
withTransaction,
tokenStore,
- skillStore,
scheduleStore,
destroyDb,
redis,
serviceFoundryClient,
+ resolveSkillStore,
} = persistence;
const activeTurns = new ActiveTurnRegistry();
@@ -455,7 +485,6 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
resolveSandboxProviderStore,
withTransaction,
tokenStore,
- skillStore,
scheduleStore,
sessionStore,
sessionMetricsStore,
@@ -468,6 +497,7 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
oidcClient,
authenticator,
authorizer,
+ resolveSkillStore,
});
return { activeTurns, app, controller, destroyDb, redis, requestReplyRouter };
diff --git a/packages/trueforge/src/routes/skillRoutes.ts b/packages/trueforge/src/routes/skillRoutes.ts
index 5770c6d75..4bb887b15 100644
--- a/packages/trueforge/src/routes/skillRoutes.ts
+++ b/packages/trueforge/src/routes/skillRoutes.ts
@@ -10,6 +10,8 @@ import {
CreateSkillRequestSchema,
GetSkillResponseSchema,
ListAvailableSkillsResponseSchema,
+ ListSkillVersionsRequestQuerySchema,
+ ListSkillVersionsResponseSchema,
ListSkillsResponseSchema,
UpdateSkillRequestSchema,
} from '../schemas/skill';
@@ -36,6 +38,30 @@ export const listAvailableSkillsRoute = createRoute({
},
});
+/** Versions for one skill — mounted at /api/v1/skills/versions?name= (FQN or skill name). */
+export const listSkillVersionsRoute = createRoute({
+ method: 'get',
+ path: '/versions',
+ tags: [OpenApiTag.SKILLS],
+ summary: 'List skill versions',
+ description: 'Versions for one skill.',
+ 'x-fern-sdk-group-name': ['skills'],
+ 'x-fern-sdk-method-name': 'list_versions',
+ request: {
+ query: ListSkillVersionsRequestQuerySchema,
+ },
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: ListSkillVersionsResponseSchema } },
+ description: 'Skill versions.',
+ },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Authentication required.',
+ },
+ },
+});
+
export const listConfiguredSkillsRoute = createRoute({
method: 'get',
path: '/',
@@ -87,6 +113,10 @@ export const createSkillRoute = createRoute({
content: { 'application/json': { schema: RequestErrorResponseSchema } },
description: 'A skill with this name already exists.',
},
+ 424: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Unsupported because skills are managed by an external system.',
+ },
},
});
@@ -113,5 +143,9 @@ export const putSkillRoute = createRoute({
content: { 'application/json': { schema: RequestErrorResponseSchema } },
description: 'Invalid request body.',
},
+ 424: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Unsupported because skills are managed by an external system.',
+ },
},
});
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index de5dcb218..e391e26cf 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -23,6 +23,7 @@ import { LocalSandboxProvider } from '../sandbox/local/provider/LocalSandboxProv
import { getCachedLocalSandboxSupport, isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
import { toSandboxProviderFromRecord } from '../sandbox/providerUtils';
import type { ReasoningEffort } from '../schemas/modelProvider';
+import { parseGitSkill } from '../schemas/skill';
export interface McpConnection {
url: string;
@@ -129,7 +130,7 @@ export async function getMcpConnection({
/**
* Expand agent_spec skill names into git mounts from the skill store.
* Wire url/path/ref/description on the request are ignored — the store row wins.
- * Throws HTTPException(422) if any name is not registered.
+ * Throws HTTPException(422) if any name is missing or not a git skill.
*/
export async function resolveGitSkills({
tenant_id,
@@ -154,13 +155,19 @@ export async function resolveGitSkills({
message: `Unknown skill "${skill.name}" — not configured`,
});
}
+ const git = parseGitSkill(record.manifest);
+ if (git === undefined) {
+ throw new HTTPException(422, {
+ message: `Skill "${skill.name}" is not a git skill`,
+ });
+ }
resolved.push({
type: 'git',
- name: record.manifest.name,
- description: record.manifest.description,
- url: record.manifest.url,
- path: record.manifest.path ?? '',
- ref: record.manifest.ref,
+ name: git.name,
+ description: git.description,
+ url: git.url,
+ path: git.path ?? '',
+ ref: git.ref,
});
}
return resolved;
@@ -238,7 +245,7 @@ export function buildTurnSandbox(input: {
/**
* Cross-checks an AgentSpec against configured models / MCP / skills and
* sandbox capability. Throws HTTPException(422) for semantic failures.
- * Skills are admitted by name only; mounts expand at turn time.
+ * Skills must exist in the skill store (git name) or pass SFY resolve (registry FQN).
*/
export async function validateAgentSpec({
spec,
@@ -293,14 +300,7 @@ export async function validateAgentSpec({
const requestedSkills = spec.skills ?? [];
if (requestedSkills.length > 0) {
- const names = requestedSkills.map(skill => skill.name);
- const configuredNames = new Set((await skillStore.listSkills({ tenant_id, names })).map(record => record.name));
- const unknown = requestedSkills.find(skill => !configuredNames.has(skill.name));
- if (unknown !== undefined) {
- throw new HTTPException(422, {
- message: `Unknown skill "${unknown.name}" — not configured`,
- });
- }
+ await skillStore.validateAgentSkills({ tenant_id, skills: requestedSkills });
}
const wantsSandbox = spec.config.sandbox.enabled;
diff --git a/packages/trueforge/src/schemas/skill.ts b/packages/trueforge/src/schemas/skill.ts
index 008c7f68f..dc71d2461 100644
--- a/packages/trueforge/src/schemas/skill.ts
+++ b/packages/trueforge/src/schemas/skill.ts
@@ -1,16 +1,15 @@
/**
- * Configured skill domain + wire schemas: the `skill.manifest` JSONB document
- * and admin/chat list projections. Catalog file schemas live in skillCatalog.ts.
- *
- * Git field rules mirror harness git skill mounts (GitHub/GitLab HTTPS url,
- * path/ref constraints) so settings documents stay mount-compatible. Identity
- * uses NameSchema like model providers / MCP servers.
+ * Configured skill domain + wire schemas (`skill.manifest` JSONB and list projections).
+ * Catalog presets live in skillCatalog.ts.
+ * SkillManifest is a `type`-discriminated oneOf of GitSkill | TrueFoundryRegistrySkill.
*/
import { z } from '@hono/zod-openapi';
import { NameSchema } from './common';
-/** Kind of skill. Extend when non-git kinds ship. */
-export const SkillTypeSchema = z.enum(['git']).openapi('SkillType');
+const SKILL_TYPES = ['git', 'truefoundry'] as const;
+
+/** OpenAPI + persisted discriminant (`git` | `truefoundry`) — same pattern as MCPServerType. */
+export const SkillTypeSchema = z.enum(SKILL_TYPES).openapi('SkillType');
// GitHub is exactly owner/repo; GitLab allows subgroups (group[/subgroup...]/project, ≥2 segments).
const GIT_URL_REGEX =
@@ -57,29 +56,59 @@ export const SkillDescriptionSchema = z
.min(1)
.describe('Concise guidance for when the agent should use the skill.');
-/** Configured skill document persisted as `skill.manifest`. */
-export const SkillManifestObjectSchema = z
+const GitSkillSchema = z
.object({
- type: SkillTypeSchema,
+ type: z.literal(SkillTypeSchema.enum.git),
name: NameSchema,
url: SkillGitUrlSchema,
path: SkillGitPathSchema.optional(),
ref: SkillGitRefSchema,
description: SkillDescriptionSchema,
})
- .strict();
+ .strict()
+ .openapi('GitSkill');
+
+/** TrueFoundry registry catalog row: `name` is the version FQN; `display_name` is the short SFY name. */
+const TrueFoundryRegistrySkillSchema = z
+ .object({
+ type: z.literal(SkillTypeSchema.enum.truefoundry),
+ name: z.string().min(1),
+ display_name: z.string().min(1),
+ description: SkillDescriptionSchema,
+ repository_name: z.string().min(1).describe('Repo where the skill is registered.'),
+ version: z.number().int().positive(),
+ })
+ .strict()
+ .openapi('TrueFoundryRegistrySkill');
-export const SkillManifestSchema = SkillManifestObjectSchema.openapi('SkillManifest');
+export const SkillManifestSchema = z
+ .discriminatedUnion('type', [GitSkillSchema, TrueFoundryRegistrySkillSchema])
+ .openapi('SkillManifest');
+
+export type SkillManifest = z.infer<typeof SkillManifestSchema>;
+export type GitSkill = z.infer<typeof GitSkillSchema>;
+export type TrueFoundryRegistrySkill = z.infer<typeof TrueFoundryRegistrySkillSchema>;
+
+/** Narrow SkillManifest → git mount shape for turn resolve. */
+export function parseGitSkill(manifest: SkillManifest): GitSkill | undefined {
+ return manifest.type === 'git' ? manifest : undefined;
+}
+
+/** Narrow SkillManifest → TrueFoundry registry catalog shape for chat list projection. */
+export function parseTrueFoundryRegistrySkill(manifest: SkillManifest): TrueFoundryRegistrySkill | undefined {
+ return manifest.type === 'truefoundry' ? manifest : undefined;
+}
/** Admin/settings wire view: identity column plus nested manifest. */
export const ConfiguredSkillSchema = z
.object({
- name: NameSchema,
+ name: z.string().min(1),
manifest: SkillManifestSchema,
})
.strict()
.openapi('ConfiguredSkill');
+/** Create/update $ref SkillManifest so OpenAPI SkillType stays git|truefoundry. */
export const CreateSkillRequestSchema = z
.object({
manifest: SkillManifestSchema,
@@ -95,26 +124,49 @@ export const UpdateSkillRequestSchema = z
.openapi('UpdateSkillRequest');
export const GetSkillResponseSchema = z.object({ data: ConfiguredSkillSchema }).openapi('GetSkillResponse');
-export const ListSkillsResponseSchema = z
- .object({ data: z.array(ConfiguredSkillSchema) })
- .openapi('ListSkillsResponse');
/** Chat/composer read view — discovery fields only. */
export const AvailableSkillSchema = z
.object({
- name: NameSchema,
+ name: z.string().min(1).describe('Skill name.'),
description: SkillDescriptionSchema,
+ metadata: z.record(z.string(), z.string()).optional().describe('Optional skill metadata.'),
})
.strict()
.openapi('AvailableSkill');
+export const ListSkillsResponseSchema = z
+ .object({ data: z.array(ConfiguredSkillSchema) })
+ .openapi('ListSkillsResponse');
+
export const ListAvailableSkillsResponseSchema = z
.object({ data: z.array(AvailableSkillSchema) })
.openapi('ListAvailableSkillsResponse');
-export type SkillType = z.infer<typeof SkillTypeSchema>;
-export type SkillManifest = z.infer<typeof SkillManifestSchema>;
+/** Versions list query — skill name (or registry FQN). */
+export const ListSkillVersionsRequestQuerySchema = z
+ .object({
+ name: z.string().min(1).describe('Skill name.'),
+ })
+ .openapi('ListSkillVersionsRequestQuery');
+
+/** One version row for the TrueFoundry skill picker dropdown. `name` is the version FQN. */
+export const SkillVersionSchema = z
+ .object({
+ name: z.string().min(1),
+ display_name: z.string().min(1),
+ description: SkillDescriptionSchema,
+ version: z.number().int().positive(),
+ })
+ .strict()
+ .openapi('SkillVersion');
+
+export const ListSkillVersionsResponseSchema = z
+ .object({ data: z.array(SkillVersionSchema) })
+ .openapi('ListSkillVersionsResponse');
+
export type ConfiguredSkill = z.infer<typeof ConfiguredSkillSchema>;
export type CreateSkillRequest = z.infer<typeof CreateSkillRequestSchema>;
export type UpdateSkillRequest = z.infer<typeof UpdateSkillRequestSchema>;
export type AvailableSkill = z.infer<typeof AvailableSkillSchema>;
+export type SkillVersion = z.infer<typeof SkillVersionSchema>;
diff --git a/packages/trueforge/src/schemas/skillCatalog.ts b/packages/trueforge/src/schemas/skillCatalog.ts
index caa64358b..3f1eb13e5 100644
--- a/packages/trueforge/src/schemas/skillCatalog.ts
+++ b/packages/trueforge/src/schemas/skillCatalog.ts
@@ -12,10 +12,16 @@ import {
SkillTypeSchema,
} from './skill';
+/**
+ * Catalog presets are user-savable `git` entries only.
+ * `truefoundry` is TrueFoundry-managed.
+ */
+export const CatalogSkillTypeSchema = SkillTypeSchema.exclude(['truefoundry']).openapi('CatalogSkillType');
+
/** Catalog entry — discovery preset the settings UI copies into a PUT body. */
export const CatalogSkillSchema = z
.object({
- type: SkillTypeSchema,
+ type: CatalogSkillTypeSchema,
name: NameSchema,
url: SkillGitUrlSchema,
path: SkillGitPathSchema.optional(),
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts b/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
index 73bfb7350..3d08728c1 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
@@ -6,15 +6,22 @@ import { z } from 'zod';
import type { McpAuthStatus } from '../schemas/mcpServer';
import { createInternalTlsDispatcher, normalizeInternalTlsUrl, type InternalTlsOptions } from './internalTls';
+import { mapResolvedAgentSkillVersions, type ResolvedAgentSkillVersion } from './mapSfyAgentSkills';
import { parseSfyMcpAuthStatus, parseSfyMcpAuthorizeResult, type SfyMcpAuthSource } from './mapSfyMcpServers';
const INTEGRATIONS_PATH = 'v1/provider-integrations';
const INSTALLATIONS_PATH = 'v1/llm-gateway/installations';
const MCP_SERVERS_PATH = 'v1/mcp';
const TFG_AGENTS_PATH = 'internal/tfg/agents';
+const TFG_AGENT_SKILL_VERSIONS_RESOLVE_PATH = 'internal/tfg/agent-skill-versions/resolve';
+const AGENT_SKILLS_PATH = 'v1/agent-skills';
+const AGENT_SKILL_VERSIONS_PATH = 'v1/agent-skill-versions';
const SESSION_PATH = 'v1/session';
const AGENT_PERMISSIONS_PATH = 'v1/authorize/permissions';
const VEND_TOKEN_PATH = 'internal/vend-token';
+const AGENT_SKILLS_PAGE_SIZE = 100;
+/** SFY resolve `@ArrayMaxSize(50)` — chunk larger AgentSpec skill lists. */
+const AGENT_SKILL_RESOLVE_CHUNK_SIZE = 50;
/**
* Fields required to build RequestContext from ServiceFoundry `GET /v1/session`.
@@ -111,6 +118,10 @@ function listPage(response: ListResponse): unknown[] {
return Array.isArray(response) ? response : response.data;
}
+function listPaginationTotal(response: ListResponse): number | undefined {
+ return Array.isArray(response) ? undefined : response.pagination?.total;
+}
+
export class TrueFoundryServiceFoundryServerClient {
readonly #baseUrl: string;
readonly #logger: Logger;
@@ -125,7 +136,7 @@ export class TrueFoundryServiceFoundryServerClient {
tls: InternalTlsOptions;
httpTimeoutMs: number;
httpAgentTimeoutMs: number;
- /** Service API key for `vend-token` only; user calls still pass a bearer `accessToken`. */
+ /** Service API key for vend-token and other privileged SFY calls. */
apiKey: string;
}) {
const tls = input.tls;
@@ -249,6 +260,101 @@ export class TrueFoundryServiceFoundryServerClient {
});
}
+ /** `GET /v1/agent-skills` with empty skills excluded. */
+ async listAgentSkills(input: { accessToken: string }): Promise<unknown[]> {
+ return this.#listAllPages({
+ path: AGENT_SKILLS_PATH,
+ accessToken: input.accessToken,
+ query: { include_empty_agent_skills: 'false' },
+ limit: AGENT_SKILLS_PAGE_SIZE,
+ });
+ }
+
+ /**
+ * `POST /internal/tfg/agent-skill-versions/resolve`. Chunks to 50 FQNs.
+ * Caller supplies the token (caller JWT on save validate).
+ * Failures: SFY HTTP errors from `#requestJson` (401/403/424/500); unexpected body → 500.
+ */
+ async resolveAgentSkillVersions(input: {
+ accessToken: string;
+ skills: readonly { fqn: string }[];
+ }): Promise<ResolvedAgentSkillVersion[]> {
+ if (input.skills.length === 0) {
+ return [];
+ }
+ const resolved: ResolvedAgentSkillVersion[] = [];
+ for (let i = 0; i < input.skills.length; i += AGENT_SKILL_RESOLVE_CHUNK_SIZE) {
+ const chunk = input.skills.slice(i, i + AGENT_SKILL_RESOLVE_CHUNK_SIZE);
+ const payload = await this.#requestJson({
+ url: this.#url(TFG_AGENT_SKILL_VERSIONS_RESOLVE_PATH),
+ accessToken: input.accessToken,
+ method: 'POST',
+ body: { skills: chunk.map(({ fqn }) => ({ fqn })) },
+ });
+ try {
+ resolved.push(...mapResolvedAgentSkillVersions(payload));
+ } catch (error) {
+ this.#logger.error('TrueFoundry ServiceFoundry resolve agent-skill-versions returned an unexpected response', {
+ ...extractErrorLogFields(error),
+ });
+ throw new HTTPException(500, {
+ message: 'TrueFoundry ServiceFoundry resolve agent-skill-versions returned an unexpected response',
+ cause: error,
+ });
+ }
+ }
+ return resolved;
+ }
+
+ /** `GET /v1/agent-skill-versions?fqn=` (one row) or `?agent_skill_id=` (all versions). */
+ async listAgentSkillVersions(input: {
+ accessToken: string;
+ fqn?: string;
+ agent_skill_id?: string;
+ }): Promise<unknown[]> {
+ const query: Record<string, string> = {};
+ if (input.fqn !== undefined) {
+ query['fqn'] = input.fqn;
+ }
+ if (input.agent_skill_id !== undefined) {
+ query['agent_skill_id'] = input.agent_skill_id;
+ }
+ return this.#listAllPages({
+ path: AGENT_SKILL_VERSIONS_PATH,
+ accessToken: input.accessToken,
+ query,
+ limit: AGENT_SKILLS_PAGE_SIZE,
+ });
+ }
+
+ /** Offset/limit list until empty page or `pagination.total`. */
+ async #listAllPages(input: {
+ path: string;
+ accessToken: string;
+ query?: Record<string, string>;
+ limit: number;
+ }): Promise<unknown[]> {
+ const items: unknown[] = [];
+ for (;;) {
+ const payload = await this.#requestJson({
+ url: this.#url(input.path, {
+ ...input.query,
+ offset: String(items.length),
+ limit: String(input.limit),
+ }),
+ accessToken: input.accessToken,
+ method: 'GET',
+ });
+ const response = this.#parseListResponse(payload);
+ const page = listPage(response);
+ items.push(...page);
+ const total = listPaginationTotal(response);
+ if (page.length === 0 || (total !== undefined && items.length >= total)) {
+ return items;
+ }
+ }
+ }
+
/** Per-subject authorize; includes a consent URL when auth is required. */
async getMcpAuthorize(input: {
accessToken: string;
diff --git a/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts b/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts
new file mode 100644
index 000000000..1e954283d
--- /dev/null
+++ b/packages/trueforge/src/truefoundry/TrueFoundrySkillStore.ts
@@ -0,0 +1,155 @@
+import { HTTPException } from 'hono/http-exception';
+import type { Logger } from 'winston';
+import type { RequestContext } from '../auth/identity';
+import type { AgentRecord } from '../db/agentStore';
+import type {
+ AgentSkillsInput,
+ CreateSkillInput,
+ ISkillStore,
+ ListSkillsInput,
+ SkillRecord,
+ UpsertSkillInput,
+} from '../db/skillStore';
+import type { SkillVersion, TrueFoundryRegistrySkill } from '../schemas/skill';
+import { accessTokenForRequest, asTrueFoundryRequestContext, type ResolveAccessToken } from './accessToken';
+import { trueFoundryManaged } from './errors';
+import {
+ mapSfyRegistrySkills,
+ mapSfyRegistrySkillVersions,
+ parseSfyRegistrySkillVersion,
+ type SfyRegistrySkill,
+} from './mapSfyAgentSkills';
+import type { TrueFoundryServiceFoundryServerClient } from './TrueFoundryServiceFoundryServerClient';
+
+export type TrueFoundrySkillApiClient = Pick<
+ TrueFoundryServiceFoundryServerClient,
+ 'listAgentSkills' | 'listAgentSkillVersions' | 'vendToken' | 'resolveAgentSkillVersions'
+>;
+
+function toRegistryRecord(tenant_id: string, skill: SfyRegistrySkill): SkillRecord {
+ const now = new Date().toISOString();
+ const manifest: TrueFoundryRegistrySkill = {
+ type: 'truefoundry',
+ name: skill.name,
+ display_name: skill.display_name,
+ description: skill.description,
+ repository_name: skill.repository_name,
+ version: skill.version,
+ };
+ return {
+ tenant_id,
+ name: skill.name,
+ manifest,
+ created_at: now,
+ updated_at: now,
+ };
+}
+
+/** Read-only TrueFoundry registry skill catalog; writes are managed by TrueFoundry.
+ * Pass `agent` on turn/cron paths so catalog reads use the same vend token as models and MCP.
+ */
+export class TrueFoundrySkillStore<TTransaction = never> implements ISkillStore<TTransaction> {
+ readonly #client: TrueFoundrySkillApiClient;
+ readonly #resolveAccessToken: ResolveAccessToken;
+
+ constructor(input: {
+ client: TrueFoundrySkillApiClient;
+ context: RequestContext;
+ agent: AgentRecord | undefined;
+ logger: Logger;
+ }) {
+ this.#client = input.client;
+ this.#resolveAccessToken = accessTokenForRequest({
+ client: input.client,
+ context: asTrueFoundryRequestContext(input.context),
+ agent: input.agent,
+ logger: input.logger,
+ });
+ }
+
+ async listSkills(input: ListSkillsInput, transaction?: TTransaction): Promise<SkillRecord[]> {
+ void transaction;
+ // Catalog list is always full; name filters belong on validateAgentSkills (SFY resolve).
+ if (input.names !== undefined) {
+ throw new HTTPException(422, {
+ message: 'TrueFoundry skill list does not support name filters',
+ });
+ }
+ const accessToken = await this.#resolveAccessToken();
+ const skills = mapSfyRegistrySkills(await this.#client.listAgentSkills({ accessToken }));
+ return skills.map(skill => toRegistryRecord(input.tenant_id, skill));
+ }
+
+ createSkill(input: CreateSkillInput, transaction?: TTransaction): Promise<SkillRecord> {
+ void input;
+ void transaction;
+ return trueFoundryManaged();
+ }
+
+ upsertSkill(input: UpsertSkillInput, transaction?: TTransaction): Promise<SkillRecord> {
+ void input;
+ void transaction;
+ return trueFoundryManaged();
+ }
+
+ async listSkillVersions(input: { name: string }): Promise<SkillVersion[]> {
+ const accessToken = await this.#resolveAccessToken();
+ // `?fqn=` returns one version; use its agent_skill_id to list every version.
+ const [version] = await this.#client.listAgentSkillVersions({
+ accessToken,
+ fqn: input.name,
+ });
+ if (version === undefined) {
+ return [];
+ }
+ const { agent_skill_id } = parseSfyRegistrySkillVersion(version);
+ const rows = await this.#client.listAgentSkillVersions({
+ accessToken,
+ agent_skill_id,
+ });
+ return mapSfyRegistrySkillVersions(rows);
+ }
+
+ async validateAgentSkills(input: AgentSkillsInput, transaction?: TTransaction): Promise<void> {
+ void transaction;
+ const { skills } = input;
+ if (skills.length === 0) {
+ return;
+ }
+
+ const seenFqns = new Set<string>();
+ for (const skill of skills) {
+ if (seenFqns.has(skill.name)) {
+ throw new HTTPException(422, {
+ message: `Duplicate skill FQN "${skill.name}"`,
+ });
+ }
+ seenFqns.add(skill.name);
+ }
+
+ const accessToken = await this.#resolveAccessToken();
+ const resolved = await this.#client.resolveAgentSkillVersions({
+ accessToken,
+ skills: skills.map(skill => ({ fqn: skill.name })),
+ });
+
+ const byFqn = new Map(resolved.map(row => [row.fqn, row]));
+ for (const skill of skills) {
+ if (!byFqn.has(skill.name)) {
+ throw new HTTPException(422, {
+ message: `Unknown skill "${skill.name}" — not configured`,
+ });
+ }
+ }
+
+ const seenNames = new Set<string>();
+ for (const row of resolved) {
+ if (seenNames.has(row.name)) {
+ throw new HTTPException(422, {
+ message: `Agent skills must have unique names; duplicate skill name(s): ${row.name}`,
+ });
+ }
+ seenNames.add(row.name);
+ }
+ }
+}
diff --git a/packages/trueforge/src/truefoundry/accessToken.ts b/packages/trueforge/src/truefoundry/accessToken.ts
index 793bae0b9..cb006e384 100644
--- a/packages/trueforge/src/truefoundry/accessToken.ts
+++ b/packages/trueforge/src/truefoundry/accessToken.ts
@@ -73,7 +73,7 @@ export function agentAccessToken(input: {
export function callerAccessToken(context: RequestContext): ResolveAccessToken {
if (context.user_credential === null) {
throw new HTTPException(401, {
- message: 'Authentication token required to list or call TrueFoundry models, MCP servers, and agents',
+ message: 'Authentication token required to list or call TrueFoundry models, MCP servers, skills, and agents',
});
}
const token = context.user_credential;
@@ -82,7 +82,7 @@ export function callerAccessToken(context: RequestContext): ResolveAccessToken {
/**
* Token for a TrueFoundry request, optionally scoped to the saved agent executing a turn.
- * Saved-agent callables are stored on this request's context so model and MCP stores share one vend.
+ * Saved-agent callables are stored on this request's context so model, MCP, and skill stores share one vend.
*/
export function accessTokenForRequest(input: {
client: AgentTokenVendor;
diff --git a/packages/trueforge/src/truefoundry/mapSfyAgentSkills.ts b/packages/trueforge/src/truefoundry/mapSfyAgentSkills.ts
new file mode 100644
index 000000000..53da7aa05
--- /dev/null
+++ b/packages/trueforge/src/truefoundry/mapSfyAgentSkills.ts
@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import type { SkillVersion } from '../schemas/skill';
+
+/** TrueFoundry skill version manifest (SFY wire). */
+const SfyRegistryManifestSchema = z.object({
+ // Display label only — not TF ResourceName / DNS-label rules.
+ name: z.string().min(1),
+ version: z.number().int().positive(),
+ // SFY field is `ml_repo`; TrueForge wire is `repository_name`.
+ ml_repo: z.string().min(1),
+ source: z
+ .object({
+ description: z.string().min(1).optional(),
+ })
+ .optional(),
+});
+
+const SfyRegistrySkillSchema = z
+ .object({
+ latest_version: z.object({
+ fqn: z.string().min(1),
+ manifest: SfyRegistryManifestSchema,
+ }),
+ })
+ .transform(({ latest_version }) => ({
+ // Wire identity is the version FQN; short SFY name is display-only.
+ name: latest_version.fqn,
+ display_name: latest_version.manifest.name,
+ description: latest_version.manifest.source?.description ?? latest_version.manifest.name,
+ repository_name: latest_version.manifest.ml_repo,
+ version: latest_version.manifest.version,
+ }));
+
+const SfyRegistrySkillVersionSchema = z.object({
+ agent_skill_id: z.string().min(1),
+ fqn: z.string().min(1),
+ manifest: SfyRegistryManifestSchema,
+});
+
+export type SfyRegistrySkill = z.infer<typeof SfyRegistrySkillSchema>;
+
+/** One resolved skill version from `…/agent-skill-versions/resolve`. */
+export const ResolvedAgentSkillVersionSchema = z.object({
+ fqn: z.string().min(1),
+ name: z.string().min(1),
+ description: z.string().min(1),
+});
+
+export type ResolvedAgentSkillVersion = z.infer<typeof ResolvedAgentSkillVersionSchema>;
+
+const ResolveAgentSkillVersionsResponseSchema = z.object({
+ skills: z.array(ResolvedAgentSkillVersionSchema),
+});
+
+/** Parse SFY registry skill list rows into the catalog wire shape. */
+export function mapSfyRegistrySkills(rows: readonly unknown[]): SfyRegistrySkill[] {
+ return rows.map(row => SfyRegistrySkillSchema.parse(row));
+}
+
+/** Parse one SFY agent-skill-version. */
+export function parseSfyRegistrySkillVersion(version: unknown): z.infer<typeof SfyRegistrySkillVersionSchema> {
+ return SfyRegistrySkillVersionSchema.parse(version);
+}
+
+/** Map SFY registry skill-version rows for the versions dropdown. */
+export function mapSfyRegistrySkillVersions(rows: readonly unknown[]): SkillVersion[] {
+ return rows.map(row => {
+ const { fqn, manifest } = SfyRegistrySkillVersionSchema.parse(row);
+ return {
+ name: fqn,
+ display_name: manifest.name,
+ description: manifest.source?.description ?? manifest.name,
+ version: manifest.version,
+ };
+ });
+}
+
+/** Parse resolve response body. */
+export function mapResolvedAgentSkillVersions(payload: unknown): ResolvedAgentSkillVersion[] {
+ return ResolveAgentSkillVersionsResponseSchema.parse(payload).skills;
+}
diff --git a/packages/trueforge/tests/db/skillStoreContractSuite.ts b/packages/trueforge/tests/db/skillStoreContractSuite.ts
index 499121547..d56c11e2d 100644
--- a/packages/trueforge/tests/db/skillStoreContractSuite.ts
+++ b/packages/trueforge/tests/db/skillStoreContractSuite.ts
@@ -3,11 +3,11 @@
* Runs under jest against a fresh store per test (see backend test files).
*/
import { SkillNameConflictError, type ISkillStore } from '../../src/db/skillStore';
-import type { SkillManifest } from '../../src/schemas/skill';
+import type { GitSkill } from '../../src/schemas/skill';
const TENANT = 'default';
-function manifest(overrides: Partial<SkillManifest> = {}): SkillManifest {
+function manifest(overrides: Partial<GitSkill> = {}): GitSkill {
return {
type: 'git',
name: 'algorithmic-art',
@@ -36,8 +36,8 @@ export function runSkillStoreContractSuite(getStore: () => ISkillStore): void {
expect(created.created_at).toMatch(ISO_UTC);
expect(created.updated_at).toBe(created.created_at);
- const fetched = await store.getSkill({ tenant_id: TENANT, name: 'algorithmic-art' });
- expect(fetched).toEqual(created);
+ const skills = await store.listSkills({ tenant_id: TENANT, names: undefined });
+ expect(skills).toEqual([created]);
});
it('createSkill inserts and throws SkillNameConflictError on name clash', async () => {
@@ -54,11 +54,6 @@ export function runSkillStoreContractSuite(getStore: () => ISkillStore): void {
).rejects.toBeInstanceOf(SkillNameConflictError);
});
- it('getSkill returns undefined for unknown skills', async () => {
- const store = getStore();
- expect(await store.getSkill({ tenant_id: TENANT, name: 'missing' })).toBeUndefined();
- });
-
it('upsert replaces the whole manifest and preserves created_at', async () => {
const store = getStore();
const created = await store.upsertSkill({
@@ -108,6 +103,57 @@ export function runSkillStoreContractSuite(getStore: () => ISkillStore): void {
expect(skills.every(skill => skill.tenant_id === TENANT)).toBe(true);
});
+ it('validateAgentSkills admits known names and rejects the first missing', async () => {
+ const store = getStore();
+ await store.upsertSkill({ tenant_id: TENANT, name: 'algorithmic-art', manifest: manifest() });
+ await store.upsertSkill({
+ tenant_id: TENANT,
+ name: 'web-artifacts',
+ manifest: manifest({
+ name: 'web-artifacts',
+ path: 'skills/web-artifacts-builder',
+ description: 'Build web artifacts.',
+ }),
+ });
+
+ await expect(
+ store.validateAgentSkills({
+ tenant_id: TENANT,
+ skills: [
+ { name: 'web-artifacts', preload: false },
+ { name: 'algorithmic-art', preload: false },
+ ],
+ }),
+ ).resolves.toBeUndefined();
+ await expect(store.validateAgentSkills({ tenant_id: TENANT, skills: [] })).resolves.toBeUndefined();
+ await expect(
+ store.validateAgentSkills({
+ tenant_id: TENANT,
+ skills: [
+ { name: 'algorithmic-art', preload: false },
+ { name: 'missing', preload: false },
+ ],
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: 'Unknown skill "missing" — not configured',
+ });
+ });
+
+ it('validateAgentSkills rejects preload on git skills', async () => {
+ const store = getStore();
+ await store.upsertSkill({ tenant_id: TENANT, name: 'algorithmic-art', manifest: manifest() });
+ await expect(
+ store.validateAgentSkills({
+ tenant_id: TENANT,
+ skills: [{ name: 'algorithmic-art', preload: true }],
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: 'Skill "algorithmic-art": preload is not supported for git skills',
+ });
+ });
+
it('listSkills filters by names and returns empty for an empty name list', async () => {
const store = getStore();
await store.upsertSkill({ tenant_id: TENANT, name: 'algorithmic-art', manifest: manifest() });
@@ -134,4 +180,10 @@ export function runSkillStoreContractSuite(getStore: () => ISkillStore): void {
await expect(store.listSkills({ tenant_id: TENANT, names: [] })).resolves.toEqual([]);
});
+
+ it('listSkillVersions returns [] in standalone (no registry versions)', async () => {
+ const store = getStore();
+ await store.upsertSkill({ tenant_id: TENANT, name: 'algorithmic-art', manifest: manifest() });
+ await expect(store.listSkillVersions({ name: 'algorithmic-art' })).resolves.toEqual([]);
+ });
}
diff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.ts
index 795ce5a12..e0da8cb45 100644
--- a/packages/trueforge/tests/unit/apis/agents.test.ts
+++ b/packages/trueforge/tests/unit/apis/agents.test.ts
@@ -93,7 +93,7 @@ describe('agents router', () => {
resolveAgentStore: () => agentStore,
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => new SqliteMcpServerStore(db),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
withTransaction: callback => db.transaction().execute(callback),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
@@ -103,7 +103,7 @@ describe('agents router', () => {
resolveAgentStore: () => agentStore,
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => new SqliteMcpServerStore(db),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
withTransaction: callback => db.transaction().execute(callback),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
diff --git a/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts b/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
index 3f81fe563..4c48f6f63 100644
--- a/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
+++ b/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
@@ -48,7 +48,7 @@ describe('public CRUD after session deletion', () => {
activeTurns,
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => mcpServerStore,
- skillStore,
+ resolveSkillStore: () => skillStore,
resolveAgentStore: () => agentStore,
resolveSandboxProviderStore: () => sandboxProviderStore,
redis: createClient(),
@@ -66,7 +66,7 @@ describe('public CRUD after session deletion', () => {
activeTurns,
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => mcpServerStore,
- skillStore,
+ resolveSkillStore: () => skillStore,
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => sandboxProviderStore,
diff --git a/packages/trueforge/tests/unit/apis/modelProviders.test.ts b/packages/trueforge/tests/unit/apis/modelProviders.test.ts
index a6478c26e..3948ef86f 100644
--- a/packages/trueforge/tests/unit/apis/modelProviders.test.ts
+++ b/packages/trueforge/tests/unit/apis/modelProviders.test.ts
@@ -104,7 +104,7 @@ async function createRouters(): Promise<{
clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
}),
tokenStore,
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
withTransaction: callback => db.transaction().execute(callback),
logger: winston.createLogger({ silent: true }),
diff --git a/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts b/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
index 5543c9074..3ad136a6c 100644
--- a/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
+++ b/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
@@ -47,7 +47,7 @@ async function buildApp() {
tokenStore,
clientName: 'test-client',
}),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index 3216b79a8..7c4acee2a 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -89,7 +89,7 @@ describe('sessions HTTP agent binding', () => {
activeTurns: new ActiveTurnRegistry(),
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => mcpServerStore,
- skillStore,
+ resolveSkillStore: () => skillStore,
resolveAgentStore: () => agentStore,
resolveSandboxProviderStore: () => sandboxProviderStore,
redis: createClient(),
diff --git a/packages/trueforge/tests/unit/apis/skills.test.ts b/packages/trueforge/tests/unit/apis/skills.test.ts
index 829372d33..f2257f13e 100644
--- a/packages/trueforge/tests/unit/apis/skills.test.ts
+++ b/packages/trueforge/tests/unit/apis/skills.test.ts
@@ -8,6 +8,7 @@ import { SkillCatalog } from '../../../src/catalog/SkillCatalog';
import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
+import { TRUEFOUNDRY_MANAGED_MESSAGE, trueFoundryManaged } from '../../../src/truefoundry/errors';
const putBody = {
type: 'git' as const,
@@ -52,7 +53,7 @@ describe('skills routers', () => {
await migrateSqliteToLatest(db);
const skillStore = new SqliteSkillStore(db);
settingsRouter = createSkillsRouter({
- skillStore,
+ resolveSkillStore: () => skillStore,
withTransaction: callback => db.transaction().execute(callback),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
});
@@ -63,7 +64,7 @@ describe('skills routers', () => {
sandboxCatalog: SandboxCatalog.load(),
});
availableRouter = createAvailableSkillsRouter({
- skillStore,
+ resolveSkillStore: () => skillStore,
withTransaction: callback => db.transaction().execute(callback),
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
});
@@ -107,7 +108,7 @@ describe('skills routers', () => {
});
});
- it('GET / on the chat router returns the slim name/description projection', async () => {
+ it('GET / on the chat router returns name and description for git skills', async () => {
const response = await availableRouter.request('/');
expect(response.status).toBe(200);
expect(await response.json()).toEqual({
@@ -118,6 +119,130 @@ describe('skills routers', () => {
});
});
+ it('GET / maps registry rows with TrueFoundry metadata', async () => {
+ const fqn = 'agent-skill:acme/team-a/echo:3';
+ const now = '2026-01-01T00:00:00.000Z';
+ const skillStore = {
+ listSkills: jest.fn().mockResolvedValue([
+ {
+ tenant_id: 'default',
+ name: fqn,
+ manifest: {
+ type: 'truefoundry' as const,
+ name: fqn,
+ display_name: 'echo',
+ description: 'Echo skill',
+ repository_name: 'team-a',
+ version: 3,
+ },
+ created_at: now,
+ updated_at: now,
+ },
+ ]),
+ createSkill: jest.fn(),
+ upsertSkill: jest.fn(),
+ listSkillVersions: jest.fn(),
+ validateAgentSkills: jest.fn(),
+ };
+ const router = createAvailableSkillsRouter({
+ resolveSkillStore: () => skillStore,
+ withTransaction: async callback => callback(undefined as never),
+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
+ });
+ const response = await router.request('/');
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({
+ data: [
+ {
+ name: fqn,
+ description: 'Echo skill',
+ metadata: {
+ display_name: 'echo',
+ repository_name: 'team-a',
+ version: '3',
+ },
+ },
+ ],
+ });
+ });
+
+ it('settings create/put forward registry bodies to the store (no early git-only 400)', async () => {
+ const registryManifest = {
+ type: 'truefoundry' as const,
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'Echo skill',
+ repository_name: 'team-a',
+ version: 3,
+ };
+ const now = '2026-01-01T00:00:00.000Z';
+ const record = {
+ tenant_id: 'default',
+ name: 'agent-skill:acme/team-a/echo:3' as const,
+ manifest: registryManifest,
+ created_at: now,
+ updated_at: now,
+ };
+ const managedStore = {
+ listSkills: jest.fn(),
+ createSkill: jest.fn().mockResolvedValue(record),
+ upsertSkill: jest.fn().mockResolvedValue(record),
+ listSkillVersions: jest.fn(),
+ validateAgentSkills: jest.fn(),
+ };
+ const router = createSkillsRouter({
+ resolveSkillStore: () => managedStore,
+ withTransaction: async callback => callback(undefined as never),
+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
+ });
+ const created = await router.request('/', postInit(wrapManifest(registryManifest)));
+ expect(created.status).toBe(201);
+ expect(managedStore.createSkill).toHaveBeenCalledWith({
+ tenant_id: 'default',
+ name: 'agent-skill:acme/team-a/echo:3',
+ manifest: registryManifest,
+ });
+
+ const put = await router.request('/', putInit(wrapManifest(registryManifest)));
+ expect(put.status).toBe(200);
+ expect(managedStore.upsertSkill).toHaveBeenCalledWith({
+ tenant_id: 'default',
+ name: 'agent-skill:acme/team-a/echo:3',
+ manifest: registryManifest,
+ });
+ });
+
+ it('settings create/put return 424 when the skill store is TrueFoundry-managed', async () => {
+ const registryManifest = {
+ type: 'truefoundry' as const,
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'Echo skill',
+ repository_name: 'team-a',
+ version: 3,
+ };
+ const managedStore = {
+ listSkills: jest.fn(),
+ createSkill: jest.fn(() => trueFoundryManaged()),
+ upsertSkill: jest.fn(() => trueFoundryManaged()),
+ listSkillVersions: jest.fn(),
+ validateAgentSkills: jest.fn(),
+ };
+ const router = createSkillsRouter({
+ resolveSkillStore: () => managedStore,
+ withTransaction: async callback => callback(undefined as never),
+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
+ });
+
+ const created = await router.request('/', postInit(wrapManifest(registryManifest)));
+ expect(created.status).toBe(424);
+ expect(await created.text()).toBe(TRUEFOUNDRY_MANAGED_MESSAGE);
+
+ const put = await router.request('/', putInit(wrapManifest(registryManifest)));
+ expect(put.status).toBe(424);
+ expect(await put.text()).toBe(TRUEFOUNDRY_MANAGED_MESSAGE);
+ });
+
it('PUT rejects invalid bodies at the Zod layer', async () => {
const { url: _, ...withoutUrl } = putBody;
const missingUrl = await settingsRouter.request('/', putInit(wrapManifest(withoutUrl)));
diff --git a/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts b/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts
index f9fc4d1f7..eb270a7ca 100644
--- a/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts
+++ b/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts
@@ -75,7 +75,7 @@ async function postTurnRejectingWith(error: AgentHarnessError): Promise<Response
tokenStore,
clientName: 'test-client',
}),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
diff --git a/packages/trueforge/tests/unit/apis/turns.test.ts b/packages/trueforge/tests/unit/apis/turns.test.ts
index 0aea4dae3..d6ada3ec2 100644
--- a/packages/trueforge/tests/unit/apis/turns.test.ts
+++ b/packages/trueforge/tests/unit/apis/turns.test.ts
@@ -67,7 +67,7 @@ describe('turns', () => {
activeTurns: new ActiveTurnRegistry(),
resolveModelProviderStore: () => new SqliteModelProviderStore(db),
resolveMcpServerStore: () => mcpServerStoreWithAuth(db, tokenStore),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
@@ -143,7 +143,7 @@ describe('turns', () => {
activeTurns: new ActiveTurnRegistry(),
resolveModelProviderStore: () => new SqliteModelProviderStore(db),
resolveMcpServerStore: () => mcpServerStoreWithAuth(db, new SqliteOAuthTokenStore(db)),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
@@ -271,7 +271,7 @@ describe('turns', () => {
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => mcpServerStoreWithAuth(db, tokenStore),
resolveAgentStore: () => new SqliteAgentStore(db),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
eventSubscriptions,
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
logger,
@@ -377,7 +377,7 @@ describe('turns', () => {
activeTurns: new ActiveTurnRegistry(),
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => mcpServerStoreWithAuth(db, tokenStore),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveAgentStore: () => new SqliteAgentStore(db),
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
@@ -457,7 +457,7 @@ describe('turns', () => {
activeTurns: new ActiveTurnRegistry(),
resolveModelProviderStore: () => new SqliteModelProviderStore(db),
resolveMcpServerStore: () => mcpServerStoreWithAuth(db, tokenStore),
- skillStore: new SqliteSkillStore(db),
+ resolveSkillStore: () => new SqliteSkillStore(db),
resolveAgentStore: () => agentStore,
eventSubscriptions: new EventSubscriptionRegistry(undefined),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index 72391f11f..c6d9d52d0 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -283,4 +283,54 @@ describe('validateAgentSpec', () => {
).resolves.toBeUndefined();
expect(await stores.sandboxProviderStore.getSandboxProvider('default')).toBeUndefined();
});
+
+ it('allows registry skills referenced by version FQN', async () => {
+ const stores = await setup();
+ setCachedLocalSandboxSupport({
+ supported: true,
+ platform: 'darwin',
+ shell: '/bin/bash',
+ python: '/usr/bin/python3',
+ });
+ const fqn = 'agent-skill:acme/team-a/echo:1';
+ const now = '2026-01-01T00:00:00.000Z';
+ const skillStore = {
+ listSkills: async () => [
+ {
+ tenant_id: 'default',
+ name: fqn,
+ manifest: {
+ type: 'truefoundry' as const,
+ name: fqn,
+ display_name: 'echo',
+ description: 'Echo',
+ repository_name: 'team-a',
+ version: 1,
+ },
+ created_at: now,
+ updated_at: now,
+ },
+ ],
+ validateAgentSkills: async () => undefined,
+ createSkill: async () => {
+ throw new Error('unused');
+ },
+ upsertSkill: async () => {
+ throw new Error('unused');
+ },
+ listSkillVersions: async () => [],
+ };
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ instructions: 'test',
+ skills: [{ name: fqn }],
+ }),
+ tenant_id: 'default',
+ ...stores,
+ skillStore,
+ }),
+ ).resolves.toBeUndefined();
+ });
});
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundrySkillStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundrySkillStore.test.ts
new file mode 100644
index 000000000..d6b12fa10
--- /dev/null
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundrySkillStore.test.ts
@@ -0,0 +1,320 @@
+import { AgentSpecSchema } from '@truefoundry/trueforge-core/agent-session';
+import { createLogger } from 'winston';
+import type { AgentRecord } from '../../../src/db/agentStore';
+import type { CreateSkillInput } from '../../../src/db/skillStore';
+import { createTrueFoundryRequestContext } from '../../../src/truefoundry/accessToken';
+import { TRUEFOUNDRY_MANAGED_MESSAGE, TRUEFOUNDRY_MANAGED_STATUS } from '../../../src/truefoundry/errors';
+import { TrueFoundrySkillStore } from '../../../src/truefoundry/TrueFoundrySkillStore';
+
+const TENANT = 'acme';
+const ACCESS_TOKEN = 'caller-access-token';
+const AGENT_TOKEN = 'agent-vend-token';
+const LOGGER = createLogger({ silent: true });
+const SFY_SKILL = {
+ id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo',
+ name: 'echo',
+ latest_version: {
+ id: 'ver-1',
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ manifest: {
+ name: 'echo',
+ type: 'agent-skill',
+ version: 3,
+ ml_repo: 'team-a',
+ source: { type: 'blob-storage', description: 'Echo skill' },
+ },
+ },
+};
+
+const AGENT: AgentRecord = {
+ id: 'agent-1',
+ tenant_id: TENANT,
+ name: 'named',
+ manifest: AgentSpecSchema.parse({ model: { name: 'p/m' } }),
+ external_id: 'ext-agent',
+ created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
+ created_at: '2026-01-01T00:00:00.000Z',
+ updated_at: '2026-01-01T00:00:00.000Z',
+};
+
+function createStore(
+ agent: AgentRecord | undefined = undefined,
+ versions: unknown[] = [
+ {
+ id: 'ver-3',
+ agent_skill_id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ manifest: {
+ name: 'echo',
+ type: 'agent-skill',
+ version: 3,
+ ml_repo: 'team-a',
+ source: { type: 'blob-storage', description: 'v3' },
+ },
+ },
+ ],
+) {
+ const client = {
+ listAgentSkills: jest.fn().mockResolvedValue([SFY_SKILL]),
+ listAgentSkillVersions: jest
+ .fn()
+ .mockImplementation(({ fqn }: { fqn?: string }) => (fqn === undefined ? versions : [versions[0]])),
+ resolveAgentSkillVersions: jest.fn().mockResolvedValue([
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ ]),
+ vendToken: jest.fn().mockResolvedValue(AGENT_TOKEN),
+ };
+ const store = new TrueFoundrySkillStore({
+ client,
+ context: createTrueFoundryRequestContext({
+ tenant_id: TENANT,
+ subject: { id: 'user-1', type: 'user', display_name: 'user-1' },
+ roles: [],
+ user_credential: ACCESS_TOKEN,
+ }),
+ agent,
+ logger: LOGGER,
+ });
+ return { store, client };
+}
+
+describe('TrueFoundrySkillStore', () => {
+ it('lists registry catalog rows as skill records with the caller token', async () => {
+ const { store, client } = createStore();
+ const records = await store.listSkills({ tenant_id: TENANT, names: undefined });
+ expect(client.listAgentSkills).toHaveBeenCalledWith({ accessToken: ACCESS_TOKEN });
+ expect(client.vendToken).not.toHaveBeenCalled();
+ expect(records).toHaveLength(1);
+ expect(records[0]?.name).toBe('agent-skill:acme/team-a/echo:3');
+ expect(records[0]?.manifest).toEqual({
+ type: 'truefoundry',
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'Echo skill',
+ repository_name: 'team-a',
+ version: 3,
+ });
+ });
+
+ it('listSkills uses latest_version only (not every historic version)', async () => {
+ const { store } = createStore();
+ const records = await store.listSkills({ tenant_id: TENANT, names: undefined });
+ expect(records.map(r => (r.manifest.type === 'truefoundry' ? r.manifest.version : undefined))).toEqual([3]);
+ expect(records.map(r => r.name)).toEqual(['agent-skill:acme/team-a/echo:3']);
+ });
+
+ it('listSkills rejects name filters', async () => {
+ const { store, client } = createStore();
+ await expect(
+ store.listSkills({
+ tenant_id: TENANT,
+ names: ['agent-skill:acme/team-a/echo:3'],
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: 'TrueFoundry skill list does not support name filters',
+ });
+ expect(client.listAgentSkills).not.toHaveBeenCalled();
+ });
+
+ it('validateAgentSkills resolves version FQNs via SFY', async () => {
+ const { store, client } = createStore();
+ await expect(
+ store.validateAgentSkills({
+ tenant_id: TENANT,
+ skills: [{ name: 'agent-skill:acme/team-a/echo:3', preload: false }],
+ }),
+ ).resolves.toBeUndefined();
+ expect(client.resolveAgentSkillVersions).toHaveBeenCalledWith({
+ accessToken: ACCESS_TOKEN,
+ skills: [{ fqn: 'agent-skill:acme/team-a/echo:3' }],
+ });
+ });
+
+ it('validateAgentSkills rejects the first name missing from the resolve response', async () => {
+ const { store, client } = createStore();
+ client.resolveAgentSkillVersions.mockResolvedValue([
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ ]);
+ await expect(
+ store.validateAgentSkills({
+ tenant_id: TENANT,
+ skills: [
+ { name: 'agent-skill:acme/team-a/echo:3', preload: false },
+ { name: 'agent-skill:acme/team-a/missing:1', preload: false },
+ ],
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: 'Unknown skill "agent-skill:acme/team-a/missing:1" — not configured',
+ });
+ });
+
+ it('validateAgentSkills is a no-op for an empty skill list', async () => {
+ const { store, client } = createStore();
+ await store.validateAgentSkills({ tenant_id: TENANT, skills: [] });
+ expect(client.resolveAgentSkillVersions).not.toHaveBeenCalled();
+ });
+
+ it('uses a vend token when listing as a saved agent', async () => {
+ const { store, client } = createStore(AGENT);
+ await store.listSkills({ tenant_id: TENANT, names: undefined });
+ expect(client.vendToken).toHaveBeenCalledWith({
+ subject: { id: 'user-1', type: 'user', display_name: 'user-1' },
+ agentId: 'ext-agent',
+ tenantName: TENANT,
+ });
+ expect(client.listAgentSkills).toHaveBeenCalledWith({ accessToken: AGENT_TOKEN });
+ });
+
+ it('uses a vend token for skill versions when listing as a saved agent', async () => {
+ const { store, client } = createStore(AGENT);
+ await store.listSkillVersions({ name: 'agent-skill:acme/team-a/echo:3' });
+ expect(client.listAgentSkillVersions).toHaveBeenNthCalledWith(1, {
+ accessToken: AGENT_TOKEN,
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ });
+ expect(client.listAgentSkillVersions).toHaveBeenNthCalledWith(2, {
+ accessToken: AGENT_TOKEN,
+ agent_skill_id: 'skill-1',
+ });
+ });
+
+ it('listSkillVersions returns every SFY version row', async () => {
+ const { store } = createStore(undefined, [
+ {
+ id: 'ver-1',
+ agent_skill_id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo:1',
+ manifest: {
+ name: 'echo',
+ type: 'agent-skill',
+ version: 1,
+ ml_repo: 'team-a',
+ source: { type: 'blob-storage', description: 'v1' },
+ },
+ },
+ {
+ id: 'ver-2',
+ agent_skill_id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo:2',
+ manifest: {
+ name: 'echo',
+ type: 'agent-skill',
+ version: 2,
+ ml_repo: 'team-a',
+ source: { type: 'blob-storage', description: 'v2' },
+ },
+ },
+ {
+ id: 'ver-3',
+ agent_skill_id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ manifest: {
+ name: 'echo',
+ type: 'agent-skill',
+ version: 3,
+ ml_repo: 'team-a',
+ source: { type: 'blob-storage', description: 'v3' },
+ },
+ },
+ ]);
+ await expect(store.listSkillVersions({ name: 'agent-skill:acme/team-a/echo:3' })).resolves.toEqual([
+ {
+ name: 'agent-skill:acme/team-a/echo:1',
+ display_name: 'echo',
+ description: 'v1',
+ version: 1,
+ },
+ {
+ name: 'agent-skill:acme/team-a/echo:2',
+ display_name: 'echo',
+ description: 'v2',
+ version: 2,
+ },
+ {
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'v3',
+ version: 3,
+ },
+ ]);
+ });
+
+ it('returns versions by FQN and rejects managed writes', async () => {
+ const { store, client } = createStore();
+ await expect(store.listSkillVersions({ name: 'agent-skill:acme/team-a/echo:3' })).resolves.toEqual([
+ {
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'v3',
+ version: 3,
+ },
+ ]);
+ expect(client.listAgentSkillVersions).toHaveBeenNthCalledWith(1, {
+ accessToken: ACCESS_TOKEN,
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ });
+ expect(client.listAgentSkillVersions).toHaveBeenNthCalledWith(2, {
+ accessToken: ACCESS_TOKEN,
+ agent_skill_id: 'skill-1',
+ });
+ const input: CreateSkillInput = {
+ tenant_id: TENANT,
+ name: 'echo',
+ manifest: {
+ type: 'git',
+ name: 'echo',
+ description: 'Echo',
+ url: 'https://github.com/acme/echo',
+ ref: 'main',
+ },
+ };
+ for (const write of [() => store.createSkill(input), () => store.upsertSkill(input)]) {
+ try {
+ write();
+ throw new Error('expected managed HTTPException');
+ } catch (error) {
+ expect(error).toMatchObject({
+ status: TRUEFOUNDRY_MANAGED_STATUS,
+ message: TRUEFOUNDRY_MANAGED_MESSAGE,
+ });
+ }
+ }
+ });
+
+ it('listSkills matches AgentSpec refs by registry FQN', async () => {
+ const { store } = createStore();
+ const records = await store.listSkills({ tenant_id: TENANT, names: undefined });
+ expect(records).toHaveLength(1);
+ expect(records[0]?.name).toBe('agent-skill:acme/team-a/echo:3');
+ });
+
+ it('validateAgentSkills uses the caller token on resolve', async () => {
+ const { store, client } = createStore();
+ client.resolveAgentSkillVersions.mockResolvedValue([
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ ]);
+ await store.validateAgentSkills({
+ tenant_id: TENANT,
+ skills: [{ name: 'agent-skill:acme/team-a/echo:3', preload: false }],
+ });
+ expect(client.resolveAgentSkillVersions).toHaveBeenCalledWith({
+ accessToken: ACCESS_TOKEN,
+ skills: [{ fqn: 'agent-skill:acme/team-a/echo:3' }],
+ });
+ });
+});
diff --git a/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts b/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts
index 570090f73..124e2a100 100644
--- a/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/accessToken.test.ts
@@ -120,15 +120,21 @@ describe('accessTokenForRequest', () => {
expect(client.vendToken).toHaveBeenCalledTimes(1);
});
- it('shares one vend across stores on the same request', async () => {
+ it('shares one vend across model, MCP, and skill stores on the same request', async () => {
const client = { vendToken: jest.fn().mockResolvedValue('agent-token') };
const context = createTrueFoundryRequestContext(CONTEXT);
const model = accessTokenForRequest({ client, context, agent: AGENT, logger: LOGGER });
const mcp = accessTokenForRequest({ client, context, agent: AGENT, logger: LOGGER });
+ const skill = accessTokenForRequest({ client, context, agent: AGENT, logger: LOGGER });
expect(model).toBe(mcp);
- await expect(Promise.all([model(), mcp()])).resolves.toEqual(['agent-token', 'agent-token']);
+ expect(mcp).toBe(skill);
+ await expect(Promise.all([model(), mcp(), skill()])).resolves.toEqual([
+ 'agent-token',
+ 'agent-token',
+ 'agent-token',
+ ]);
expect(client.vendToken).toHaveBeenCalledTimes(1);
});
diff --git a/packages/trueforge/tests/unit/truefoundry/listAgentSkillsPaging.test.ts b/packages/trueforge/tests/unit/truefoundry/listAgentSkillsPaging.test.ts
new file mode 100644
index 000000000..f48394138
--- /dev/null
+++ b/packages/trueforge/tests/unit/truefoundry/listAgentSkillsPaging.test.ts
@@ -0,0 +1,43 @@
+import { createLogger, transports } from 'winston';
+import { TrueFoundryServiceFoundryServerClient } from '../../../src/truefoundry/TrueFoundryServiceFoundryServerClient';
+
+const fetchMock = jest.fn();
+
+jest.mock('undici', () => ({
+ fetch: (...args: unknown[]) => fetchMock(...args),
+}));
+
+function jsonResponse(body: unknown): { ok: true; status: 200; text: () => Promise<string> } {
+ return {
+ ok: true,
+ status: 200,
+ text: async () => JSON.stringify(body),
+ };
+}
+
+describe('TrueFoundryServiceFoundryServerClient listAgentSkills paging', () => {
+ beforeEach(() => {
+ fetchMock.mockReset();
+ });
+
+ it('continues when pagination.total is missing until an empty page', async () => {
+ const page1 = Array.from({ length: 100 }, (_, i) => ({ id: `s-${String(i)}` }));
+ const page2 = [{ id: 's-100' }];
+ fetchMock
+ .mockResolvedValueOnce(jsonResponse({ data: page1 }))
+ .mockResolvedValueOnce(jsonResponse({ data: page2 }))
+ .mockResolvedValueOnce(jsonResponse({ data: [] }));
+
+ const client = new TrueFoundryServiceFoundryServerClient({
+ serviceFoundryServerUrl: 'https://sfy.example',
+ logger: createLogger({ transports: [new transports.Console({ silent: true })] }),
+ tls: { enabled: false, dir: '' },
+ httpTimeoutMs: 5_000,
+ httpAgentTimeoutMs: 5_000,
+ apiKey: 'key',
+ });
+
+ await expect(client.listAgentSkills({ accessToken: 'token' })).resolves.toEqual([...page1, ...page2]);
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ });
+});
diff --git a/packages/trueforge/tests/unit/truefoundry/mapSfyAgentSkills.test.ts b/packages/trueforge/tests/unit/truefoundry/mapSfyAgentSkills.test.ts
new file mode 100644
index 000000000..4d0c0f899
--- /dev/null
+++ b/packages/trueforge/tests/unit/truefoundry/mapSfyAgentSkills.test.ts
@@ -0,0 +1,134 @@
+import {
+ mapResolvedAgentSkillVersions,
+ mapSfyRegistrySkills,
+ mapSfyRegistrySkillVersions,
+ parseSfyRegistrySkillVersion,
+} from '../../../src/truefoundry/mapSfyAgentSkills';
+
+const MANIFEST = {
+ name: 'echo',
+ type: 'agent-skill',
+ version: 3,
+ ml_repo: 'team-a',
+ source: { type: 'blob-storage', description: 'Echo skill' },
+};
+
+const VERSION = {
+ agent_skill_id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ manifest: MANIFEST,
+};
+
+describe('mapSfyRegistrySkills', () => {
+ it('maps list rows with latest version FQN as name', () => {
+ expect(
+ mapSfyRegistrySkills([
+ {
+ id: 'skill-1',
+ fqn: 'agent-skill:acme/team-a/echo',
+ name: 'echo',
+ latest_version: {
+ id: 'ver-1',
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ manifest: MANIFEST,
+ },
+ },
+ ]),
+ ).toEqual([
+ {
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'Echo skill',
+ repository_name: 'team-a',
+ version: 3,
+ },
+ ]);
+ });
+
+ it('maps version rows with name=FQN and display_name=short SFY name', () => {
+ expect(mapSfyRegistrySkillVersions([VERSION])).toEqual([
+ {
+ name: 'agent-skill:acme/team-a/echo:3',
+ display_name: 'echo',
+ description: 'Echo skill',
+ version: 3,
+ },
+ ]);
+ });
+
+ it('accepts SFY manifest names that are not ResourceName slugs', () => {
+ expect(
+ mapSfyRegistrySkills([
+ {
+ id: 'skill-2',
+ fqn: 'agent-skill:acme/team-a/My Skill',
+ latest_version: {
+ fqn: 'agent-skill:acme/team-a/My Skill:1',
+ manifest: {
+ name: 'My Skill',
+ version: 1,
+ ml_repo: 'team-a',
+ source: { description: 'Mixed-case display name' },
+ },
+ },
+ },
+ ]),
+ ).toEqual([
+ {
+ name: 'agent-skill:acme/team-a/My Skill:1',
+ display_name: 'My Skill',
+ description: 'Mixed-case display name',
+ repository_name: 'team-a',
+ version: 1,
+ },
+ ]);
+ });
+
+ it('parses resolve response skills', () => {
+ expect(
+ mapResolvedAgentSkillVersions({
+ skills: [
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ ],
+ }),
+ ).toEqual([
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ ]);
+ });
+
+ it('strips unknown fields on resolve responses', () => {
+ expect(
+ mapResolvedAgentSkillVersions({
+ skills: [
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ extra_sfy_field: true,
+ },
+ ],
+ pagination: { total: 1 },
+ }),
+ ).toEqual([
+ {
+ fqn: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ ]);
+ });
+});
+
+describe('parseSfyRegistrySkillVersion', () => {
+ it('reads agent_skill_id from one SFY version', () => {
+ expect(parseSfyRegistrySkillVersion(VERSION).agent_skill_id).toBe('skill-1');
+ });
+});