Skip to content

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

Add skill version picker to TrueFoundry UI (#661)

Bhavesh Patel77c5c33742aa
diff --git a/.changeset/skill-version-picker.md b/.changeset/skill-version-picker.md
new file mode 100644
index 000000000..5b1f51a9e
--- /dev/null
+++ b/.changeset/skill-version-picker.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge-ui': patch
+---
+
+Show TrueFoundry skill repositories and versions in skill pickers, load version choices lazily, preserve the chosen version FQN when attaching skills, keep picker ordering stable while open, and add registry-only preload controls to selected skill pills.
diff --git a/packages/trueforge-ui/src/atoms/draft/AgentConfigPanel.tsx b/packages/trueforge-ui/src/atoms/draft/AgentConfigPanel.tsx
index 18851fb9a..11688e843 100644
--- a/packages/trueforge-ui/src/atoms/draft/AgentConfigPanel.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/AgentConfigPanel.tsx
@@ -3,7 +3,7 @@
import { useState, type ReactNode } from 'react';
import { Icon } from '../../icons/Icon.js';
-import type { AgentSpec, ModelSelection } from '../../server/types.js';
+import type { AgentSkill, AgentSpec, ModelSelection } from '../../server/types.js';
import { useSlot } from '../../theme/SlotsProvider.js';
import { auiButtonClass } from '../lib/buttonClasses.js';
import { cn } from '../lib/cn.js';
@@ -21,6 +21,7 @@ import {
import { displayModelLabel, ProviderMark } from './DraftModelCatalogPanel.js';
import { modelParamSummary } from './modelParamsSummary.js';
import { runtimeConfigSummary, runtimeConfigValueClassName } from './runtimeConfigSummary.js';
+import { skillFamilyId, skillVersion } from './SkillVersionSelector.js';
const DEFAULT_INSTRUCTIONS =
'Enter detailed instructions for your agent. E.g. You are a helpful assistant that helps users plan trips. Always ask clarifying questions before making suggestions...';
@@ -31,6 +32,7 @@ export type AgentConfigPanelProps = {
models: ModelSelection[];
modelsLoading: boolean;
modelsError: string | null;
+ skills?: AgentSkill[];
skillsAvailable: boolean;
instructions: string;
onOpenEditor: (editor: AgentConfigEditor) => void;
@@ -122,6 +124,84 @@ function McpServerChip({
);
}
+function SkillChip({
+ item,
+ preloadAvailable,
+ onRemove,
+ onTogglePreload,
+}: {
+ item: EditableMount;
+ preloadAvailable: boolean;
+ onRemove?: () => void;
+ onTogglePreload?: () => void;
+}) {
+ const preload = preloadFromMount(item.value);
+
+ return (
+ <span className="flex items-center overflow-hidden rounded-md border border-border text-xs">
+ {preloadAvailable && onTogglePreload ? (
+ <Tooltip
+ side="bottom"
+ dismissOnClick={false}
+ triggerClassName="self-stretch"
+ className="w-64 whitespace-normal p-3 text-left shadow-lg"
+ content={
+ <span className="flex flex-col gap-1.5">
+ <span className="flex items-center justify-between gap-3">
+ <span className="font-semibold">Preload skill</span>
+ <span className="text-primary-button-bg text-[0.625rem] font-semibold tracking-wide uppercase">
+ {preload ? 'ON' : 'OFF'}
+ </span>
+ </span>
+ <span className="text-text-secondary text-xs leading-snug">
+ Inline SKILL.md in the agent context upfront. When off, the agent loads the skill dynamically.
+ </span>
+ </span>
+ }
+ >
+ <button
+ type="button"
+ aria-pressed={preload}
+ aria-label={`Preload skill ${item.name}`}
+ className={cn(
+ 'flex h-full items-center justify-center border-r border-border px-1.5 transition-colors',
+ preload
+ ? 'bg-primary-button-bg text-primary-button-text'
+ : 'text-text-secondary hover:bg-ghost-button-hover',
+ )}
+ onClick={event => {
+ event.stopPropagation();
+ onTogglePreload();
+ }}
+ >
+ <Icon name="book-open" className="size-3.5" />
+ </button>
+ </Tooltip>
+ ) : null}
+ <span className="py-1 pl-2">{item.name}</span>
+ {onRemove ? (
+ <button
+ type="button"
+ aria-label={`Remove ${item.name}`}
+ className={auiButtonClass({
+ variant: 'ghost',
+ size: 'icon',
+ className: 'mx-1 size-5',
+ })}
+ onClick={event => {
+ event.stopPropagation();
+ onRemove();
+ }}
+ >
+ <Icon name="xmark" className="size-3" />
+ </button>
+ ) : (
+ <span className="pr-2" />
+ )}
+ </span>
+ );
+}
+
export function AgentConfigSection({
title,
description,
@@ -200,6 +280,7 @@ export function AgentConfigPanel({
models,
modelsLoading,
modelsError,
+ skills: catalogSkills = [],
skillsAvailable,
instructions,
onOpenEditor,
@@ -213,7 +294,7 @@ export function AgentConfigPanel({
const [modelSettingsMenuOpen, setModelSettingsMenuOpen] = useState(false);
const [modelQuery, setModelQuery] = useState('');
const mcp = editableMountsFromSpec(spec.mcpServers);
- const skills = editableMountsFromSpec(spec.skills);
+ const skillMounts = editableMountsFromSpec(spec.skills);
const modelParams = modelParamSummary(spec.model.params);
const runtimeConfig = runtimeConfigSummary(spec.config);
const instructionPreview = instructions.trim();
@@ -429,13 +510,42 @@ export function AgentConfigPanel({
<Section title="Skills" actionIcon="plus" actionLabel="Add skill" onEdit={() => onOpenEditor('skills')}>
{!skillsAvailable ? (
<p className="text-text-secondary text-xs">Skills require an available sandbox.</p>
- ) : skills.length ? (
+ ) : skillMounts.length ? (
<div className="flex flex-wrap gap-1.5">
- {skills.map(item => (
- <span key={item.id} className="rounded-md border border-border px-2 py-1 text-xs">
- {item.name}
- </span>
- ))}
+ {skillMounts.map(item => {
+ const preloadAvailable = catalogSkills.some(
+ skill => skillVersion(skill) !== undefined && skillFamilyId(skill.id) === skillFamilyId(item.id),
+ );
+ return (
+ <SkillChip
+ key={item.id}
+ item={item}
+ preloadAvailable={preloadAvailable}
+ onRemove={
+ onChange
+ ? () =>
+ onChange({
+ ...spec,
+ skills: skillMounts.filter(mount => mount.id !== item.id).map(mount => mount.value),
+ })
+ : undefined
+ }
+ onTogglePreload={
+ preloadAvailable && onChange
+ ? () =>
+ onChange({
+ ...spec,
+ skills: skillMounts.map(mount =>
+ mount.id === item.id
+ ? withPreload(mount.value, !preloadFromMount(mount.value))
+ : mount.value,
+ ),
+ })
+ : undefined
+ }
+ />
+ );
+ })}
</div>
) : (
<p className="text-text-secondary text-xs">No skills selected.</p>
diff --git a/packages/trueforge-ui/src/atoms/draft/AgentSkillsEditorContent.tsx b/packages/trueforge-ui/src/atoms/draft/AgentSkillsEditorContent.tsx
index 843606005..c7193eef6 100644
--- a/packages/trueforge-ui/src/atoms/draft/AgentSkillsEditorContent.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/AgentSkillsEditorContent.tsx
@@ -1,10 +1,19 @@
'use client';
+import { useState } from 'react';
+
import { Icon } from '../../icons/Icon.js';
import type { AgentSkill, AgentSpec } from '../../server/types.js';
import { useSlot } from '../../theme/SlotsProvider.js';
import { auiInputClass } from '../lib/inputClasses.js';
import { editableMountsFromSpec } from './agentConfigMounts.js';
+import {
+ SkillVersionSelector,
+ skillFamilyId,
+ skillRepoName,
+ skillVersion,
+ type SkillVersionOption,
+} from './SkillVersionSelector.js';
export type AgentSkillsEditorContentProps = {
spec: AgentSpec;
@@ -24,13 +33,17 @@ export function AgentSkillsEditorContent({
onChange,
}: AgentSkillsEditorContentProps) {
const CatalogRow = useSlot('CatalogRow');
+ const [selectedVersions, setSelectedVersions] = useState<Record<string, SkillVersionOption>>({});
const skillMounts = editableMountsFromSpec(spec.skills);
+ const [initialSelectedFamilies] = useState(() => new Set(skillMounts.map(item => skillFamilyId(item.id))));
const normalizedQuery = query.trim().toLowerCase();
const filteredSkills = skills
- .filter(item => `${item.name} ${item.description ?? ''}`.toLowerCase().includes(normalizedQuery))
+ .filter(item =>
+ `${item.name} ${skillRepoName(item) ?? ''} ${item.description ?? ''}`.toLowerCase().includes(normalizedQuery),
+ )
.sort((left, right) => {
- const leftSelected = skillMounts.some(item => item.id === left.id || item.name === left.name);
- const rightSelected = skillMounts.some(item => item.id === right.id || item.name === right.name);
+ const leftSelected = initialSelectedFamilies.has(skillFamilyId(left.id));
+ const rightSelected = initialSelectedFamilies.has(skillFamilyId(right.id));
return Number(rightSelected) - Number(leftSelected);
});
@@ -47,20 +60,50 @@ export function AgentSkillsEditorContent({
</label>
<div className="min-h-0 flex-1 overflow-y-auto p-2">
{filteredSkills.map(skill => {
- const mount = skillMounts.find(item => item.id === skill.id || item.name === skill.name);
+ const mount = skillMounts.find(item => skillFamilyId(item.id) === skillFamilyId(skill.id));
+ const selectedVersion = selectedVersions[skill.id];
+ const repoName = skillRepoName(skill);
return (
<CatalogRow
key={skill.id}
title={skill.name}
description={skill.description}
+ badge={
+ repoName === undefined ? undefined : (
+ <span className="bg-primary-button-bg/10 text-primary-button-bg shrink-0 rounded-full px-1.5 py-0.5 text-[0.625rem]">
+ {repoName}
+ </span>
+ )
+ }
checked={mount !== undefined}
disabled={skillsDisabled && mount === undefined}
+ action={
+ skillVersion(skill) === undefined ? undefined : (
+ <SkillVersionSelector
+ skill={skill}
+ selectedId={selectedVersion?.id ?? mount?.id}
+ onChange={version => {
+ setSelectedVersions(previous => ({ ...previous, [skill.id]: version }));
+ if (mount === undefined) return;
+ onChange({
+ ...spec,
+ skills: skillMounts.map(item =>
+ item === mount ? { ...item.value, id: version.id, name: version.name } : item.value,
+ ),
+ });
+ }}
+ />
+ )
+ }
onToggle={() => {
const adding = mount === undefined;
onChange({
...spec,
skills: adding
- ? [...(spec.skills ?? []), { id: skill.id, name: skill.name }]
+ ? [
+ ...(spec.skills ?? []),
+ { id: selectedVersion?.id ?? skill.id, name: selectedVersion?.name ?? skill.name },
+ ]
: skillMounts.filter(item => item !== mount).map(item => item.value),
...(adding
? {
diff --git a/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx b/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx
index 15ba905df..c530ea1ae 100644
--- a/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx
@@ -21,9 +21,10 @@ import { Tooltip } from '../primitives/Tooltip.js';
import { DraftCatalogEmptyState } from './DraftCatalogEmptyState.js';
import { useDraftCatalog } from './DraftCatalogProvider.js';
import { connectorsWithSelectedStubs } from './mcpConnectorStubs.js';
+import { skillFamilyId, skillRepoName } from './SkillVersionSelector.js';
/** Catalog-backed mount shape used by the draft picker (runtime mounts stay opaque). */
-export type DraftMount = { id: string; name: string };
+export type DraftMount = { id: string; name: string; preload?: boolean };
/**
* Harness wire mounts are name-keyed (`{ name }` only). Catalog rows use
@@ -38,7 +39,13 @@ export function draftMountsFromSpec(value: unknown): DraftMount[] {
const name = Reflect.get(item, 'name');
if (typeof name !== 'string') continue;
const id = Reflect.get(item, 'id');
- mounts.push({ id: typeof id === 'string' ? id : name, name });
+ const displayName = Reflect.get(item, 'display_name');
+ const preload = Reflect.get(item, 'preload');
+ mounts.push({
+ id: typeof id === 'string' ? id : name,
+ name: typeof displayName === 'string' ? displayName : name,
+ ...(typeof preload === 'boolean' ? { preload } : {}),
+ });
}
return mounts;
}
@@ -70,6 +77,7 @@ function Checkbox({ checked }: { checked: boolean }) {
export function CatalogRow({
title,
description,
+ badge,
logo,
fallbackIcon,
checked,
@@ -80,6 +88,7 @@ export function CatalogRow({
}: {
title: string;
description?: string;
+ badge?: ReactNode;
/** Catalog logo URL; when absent, `fallbackIcon` (or the title initial) is shown. */
logo?: string | undefined;
fallbackIcon?: string;
@@ -104,7 +113,10 @@ export function CatalogRow({
)}
</span>
<span className="min-w-0 flex-1">
- <span className="text-text-primary block truncate text-sm font-medium">{title}</span>
+ <span className="flex min-w-0 items-center gap-1.5">
+ <span className="text-text-primary truncate text-sm font-medium">{title}</span>
+ {badge}
+ </span>
{description ? <span className="text-text-secondary line-clamp-1 text-xs">{description}</span> : null}
</span>
</>
@@ -125,7 +137,13 @@ export function CatalogRow({
}}
>
{content}
- <span className="shrink-0">{action}</span>
+ <span
+ className="shrink-0"
+ onClick={event => event.stopPropagation()}
+ onKeyDown={event => event.stopPropagation()}
+ >
+ {action}
+ </span>
<button
type="button"
role="checkbox"
@@ -281,7 +299,6 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
const selectedMcp = open ? localMcp : specMcp;
const selectedSkills = open ? localSkills : specSkills;
const selectedMcpIds = useMemo(() => new Set(selectedMcp.map(m => m.id)), [selectedMcp]);
- const selectedSkillIds = useMemo(() => new Set(selectedSkills.map(s => s.id)), [selectedSkills]);
const hasValidModel = Boolean(agentSpec?.model?.name.trim());
const toolsCount = selectedMcp.length + selectedSkills.length;
const toolsTooltip = useMemo(() => {
@@ -383,7 +400,10 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
const needle = query.trim().toLowerCase();
if (!needle) return skills;
return skills.filter(
- s => s.name.toLowerCase().includes(needle) || (s.description?.toLowerCase().includes(needle) ?? false),
+ skill =>
+ skill.name.toLowerCase().includes(needle) ||
+ (skillRepoName(skill)?.toLowerCase().includes(needle) ?? false) ||
+ (skill.description?.toLowerCase().includes(needle) ?? false),
);
}, [skills, query]);
@@ -396,11 +416,11 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
[filteredConnectors, pinnedMcpIds],
);
const pinnedSelectedSkills = useMemo(
- () => filteredSkills.filter(s => pinnedSkillIds.has(s.id)),
+ () => filteredSkills.filter(s => pinnedSkillIds.has(skillFamilyId(s.id))),
[filteredSkills, pinnedSkillIds],
);
const pinnedAvailableSkills = useMemo(
- () => filteredSkills.filter(s => !pinnedSkillIds.has(s.id)),
+ () => filteredSkills.filter(s => !pinnedSkillIds.has(skillFamilyId(s.id))),
[filteredSkills, pinnedSkillIds],
);
@@ -415,11 +435,12 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
};
const toggleSkill = (skill: AgentSkill) => {
- const adding = !localSkillsRef.current.some(item => item.id === skill.id);
- setLocalSkills(prev =>
- prev.some(s => s.id === skill.id)
- ? prev.filter(s => s.id !== skill.id)
- : [...prev, { id: skill.id, name: skill.name }],
+ const family = skillFamilyId(skill.id);
+ const adding = !localSkillsRef.current.some(item => skillFamilyId(item.id) === family);
+ setLocalSkills(previous =>
+ previous.some(item => skillFamilyId(item.id) === family)
+ ? previous.filter(item => skillFamilyId(item.id) !== family)
+ : [...previous, { id: skill.id, name: skill.name }],
);
if (adding && capabilities?.sandbox.enabled === true) {
updateAgentSpec?.({
@@ -433,6 +454,28 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
scheduleFlush();
};
+ const renderSkill = (skill: AgentSkill) => {
+ const selected = selectedSkills.find(mount => skillFamilyId(mount.id) === skillFamilyId(skill.id));
+ const repoName = skillRepoName(skill);
+ return (
+ <CatalogRow
+ key={skill.id}
+ title={skill.name}
+ description={skill.description}
+ badge={
+ repoName === undefined ? undefined : (
+ <span className="bg-primary-button-bg/10 text-primary-button-bg shrink-0 rounded-full px-1.5 py-0.5 text-[0.625rem]">
+ {repoName}
+ </span>
+ )
+ }
+ checked={selected !== undefined}
+ disabled={skillsDisabled && selected === undefined}
+ onToggle={() => toggleSkill(skill)}
+ />
+ );
+ };
+
const openPicker = (nextTab?: AttachTab) => {
if (nextTab != null) {
setTab(nextTab);
@@ -444,7 +487,7 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
dirtyRef.current = false;
clearFlushTimer();
setPinnedMcpIds(new Set(specMcp.map(m => m.id)));
- setPinnedSkillIds(new Set(specSkills.map(s => s.id)));
+ setPinnedSkillIds(new Set(specSkills.map(skill => skillFamilyId(skill.id))));
setOpen(true);
};
@@ -558,31 +601,13 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
{pinnedSelectedSkills.length > 0 ? (
<>
<SectionHeading label="Selected" count={pinnedSelectedSkills.length} />
- {pinnedSelectedSkills.map(s => (
- <CatalogRow
- key={s.id}
- title={s.name}
- description={s.description}
- checked={selectedSkillIds.has(s.id)}
- disabled={skillsDisabled && !selectedSkillIds.has(s.id)}
- onToggle={() => toggleSkill(s)}
- />
- ))}
+ {pinnedSelectedSkills.map(renderSkill)}
</>
) : null}
{pinnedAvailableSkills.length > 0 ? (
<>
<SectionHeading label="Available" count={pinnedAvailableSkills.length} />
- {pinnedAvailableSkills.map(s => (
- <CatalogRow
- key={s.id}
- title={s.name}
- description={s.description}
- checked={selectedSkillIds.has(s.id)}
- disabled={skillsDisabled && !selectedSkillIds.has(s.id)}
- onToggle={() => toggleSkill(s)}
- />
- ))}
+ {pinnedAvailableSkills.map(renderSkill)}
</>
) : null}
{filteredSkills.length === 0 ? (
diff --git a/packages/trueforge-ui/src/atoms/draft/SkillVersionSelector.tsx b/packages/trueforge-ui/src/atoms/draft/SkillVersionSelector.tsx
new file mode 100644
index 000000000..55f54ae42
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/draft/SkillVersionSelector.tsx
@@ -0,0 +1,137 @@
+'use client';
+
+import { useState } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import type { AgentSkill } from '../../server/types.js';
+import { getErrorMessage } from '../../utils/getErrorMessage.js';
+import { cn } from '../lib/cn.js';
+import { DropdownMenu, DropdownMenuItem } from '../primitives/DropdownMenu.js';
+
+export type SkillVersionOption = {
+ id: string;
+ name: string;
+ description?: string;
+ version: number;
+};
+
+function nonEmptyString(value: unknown): string | undefined {
+ return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+ return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function skillRepoName(skill: AgentSkill): string | undefined {
+ return nonEmptyString(Reflect.get(skill, 'skillRepoName'));
+}
+
+export function skillVersion(skill: AgentSkill): number | undefined {
+ return positiveInteger(Reflect.get(skill, 'version'));
+}
+
+export function skillFamilyId(id: string): string {
+ return id.replace(/:\d+$/, '');
+}
+
+export function versionFromSkillId(id: string): number | undefined {
+ const match = /:(\d+)$/.exec(id);
+ return match === null ? undefined : positiveInteger(Number(match[1]));
+}
+
+async function loadSkillVersions(skill: AgentSkill): Promise<SkillVersionOption[]> {
+ const loader = Reflect.get(skill, 'loadVersions');
+ if (typeof loader !== 'function') return [];
+ const rows: unknown = await Reflect.apply(loader, skill, []);
+ if (!Array.isArray(rows)) return [];
+
+ return rows.flatMap(row => {
+ if (typeof row !== 'object' || row === null) return [];
+ const id = nonEmptyString(Reflect.get(row, 'name'));
+ const name = nonEmptyString(Reflect.get(row, 'displayName'));
+ const description = nonEmptyString(Reflect.get(row, 'description'));
+ const version = positiveInteger(Reflect.get(row, 'version'));
+ if (id === undefined || name === undefined || version === undefined) return [];
+ return [{ id, name, ...(description === undefined ? {} : { description }), version }];
+ });
+}
+
+export function SkillVersionSelector({
+ skill,
+ selectedId,
+ onChange,
+}: {
+ skill: AgentSkill;
+ selectedId?: string;
+ onChange: (version: SkillVersionOption) => void;
+}) {
+ const latestVersion = skillVersion(skill);
+ const selectedVersion = selectedId === undefined ? latestVersion : versionFromSkillId(selectedId);
+ const [versions, setVersions] = useState<SkillVersionOption[] | null>(null);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ if (latestVersion === undefined) return null;
+
+ const load = () => {
+ if (versions !== null || loading) return;
+ setLoading(true);
+ setError(null);
+ void loadSkillVersions(skill)
+ .then(setVersions)
+ .catch(reason => setError(getErrorMessage(reason, 'Failed to load versions.')))
+ .finally(() => setLoading(false));
+ };
+
+ return (
+ <DropdownMenu
+ align="end"
+ onOpenChange={open => {
+ if (open) load();
+ }}
+ className="min-w-40"
+ trigger={
+ <button
+ type="button"
+ aria-label={`Select version for ${skill.name}`}
+ className="text-text-secondary hover:bg-ghost-button-hover flex h-7 items-center gap-1 rounded-md border border-border px-2 text-xs"
+ >
+ <span>v{selectedVersion ?? latestVersion}</span>
+ {selectedVersion === latestVersion ? <span className="text-primary-button-bg">latest</span> : null}
+ <Icon name="chevron-down" className="size-3" />
+ </button>
+ }
+ >
+ {loading ? <p className="text-text-secondary px-2 py-1.5 text-xs">Loading…</p> : null}
+ {error ? (
+ <div className="flex items-center justify-between gap-2 px-2 py-1.5 text-xs">
+ <p className="text-failure-bg">Failed to load versions.</p>
+ <button
+ type="button"
+ className="text-text-secondary hover:text-text-primary shrink-0 underline"
+ onClick={() => {
+ void navigator.clipboard.writeText(error).catch(() => undefined);
+ }}
+ >
+ Copy error
+ </button>
+ </div>
+ ) : null}
+ {versions?.map(option => (
+ <DropdownMenuItem
+ key={option.id}
+ aria-selected={option.id === selectedId || (selectedId === undefined && option.version === latestVersion)}
+ className={cn('justify-between', option.id === selectedId && 'font-medium')}
+ onClick={() => onChange(option)}
+ >
+ <span>v{option.version}</span>
+ {option.version === latestVersion ? <span className="text-primary-button-bg text-xs">latest</span> : null}
+ </DropdownMenuItem>
+ ))}
+ {!loading && error === null && versions?.length === 0 ? (
+ <p className="text-text-secondary px-2 py-1.5 text-xs">No versions found.</p>
+ ) : null}
+ </DropdownMenu>
+ );
+}
diff --git a/packages/trueforge-ui/src/containers/AgentConfigDrawerContainer.tsx b/packages/trueforge-ui/src/containers/AgentConfigDrawerContainer.tsx
index c3e8498f8..8026f5b8c 100644
--- a/packages/trueforge-ui/src/containers/AgentConfigDrawerContainer.tsx
+++ b/packages/trueforge-ui/src/containers/AgentConfigDrawerContainer.tsx
@@ -134,6 +134,7 @@ export function AgentConfigDrawerContainer({ showClose = false }: { showClose?:
models={catalog.models}
modelsLoading={catalog.loading}
modelsError={catalog.error}
+ skills={catalog.skills}
skillsAvailable={capabilities?.skill.enabled === true}
instructions={instructionDraft}
onOpenEditor={setEditor}
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx
index 0f345de36..62b74d00d 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx
@@ -16,6 +16,10 @@ const matchesQuery = (query: string, name: string, description: string) =>
const isRegistrySkill = (skill: SkillBase): skill is RegistrySkill => 'catalogId' in skill;
+function isManagedSkillError(error: unknown): boolean {
+ return typeof error === 'object' && error !== null && Reflect.get(error, 'statusCode') === 424;
+}
+
const SkillSettings = () => {
const { skillCatalog } = useCatalogServer();
const toaster = useToasterOptional();
@@ -27,6 +31,7 @@ const SkillSettings = () => {
const [error, setError] = useState<string | null>(null);
const [formError, setFormError] = useState<string | null>(null);
const [busy, setBusy] = useState(false);
+ const [managedExternally, setManagedExternally] = useState(false);
const [importOpen, setImportOpen] = useState(false);
const refresh = useCallback(async () => {
@@ -69,6 +74,7 @@ const SkillSettings = () => {
await fn();
await refresh();
} catch (err) {
+ if (isManagedSkillError(err)) setManagedExternally(true);
setMutationError(getErrorMessage(err, 'Request failed'));
throw err;
} finally {
@@ -160,7 +166,7 @@ const SkillSettings = () => {
<Button.Secondary
type="button"
className="shrink-0"
- disabled={busy}
+ disabled={busy || managedExternally}
onClick={() => {
setFormError(null);
setImportOpen(true);
@@ -192,7 +198,7 @@ const SkillSettings = () => {
<Button.Secondary
size="small"
type="button"
- disabled={busy}
+ disabled={busy || managedExternally}
aria-label={`Remove ${skill.name}`}
onClick={() => {
handleRemove(skill);
@@ -225,7 +231,7 @@ const SkillSettings = () => {
<Button.Secondary
size="small"
type="button"
- disabled={busy}
+ disabled={busy || managedExternally}
aria-label={`Enable ${entry.name}`}
onClick={() => {
handleSelect(entry);
@@ -255,7 +261,7 @@ const SkillSettings = () => {
if (!open) setFormError(null);
}}
onImport={handleImport}
- busy={busy}
+ busy={busy || managedExternally}
error={formError}
/>
</>
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 c13860d2a..ba0bf6397 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
@@ -88,11 +88,23 @@ export function createHarnessBuilderServer(
// 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.metadata?.display_name ?? skill.name,
- description: skill.description,
- }));
+ return skills.map(skill => {
+ const { display_name, repository_name, version: versionRaw } = skill.metadata ?? {};
+ const version = Number(versionRaw);
+ const hasVersion = Number.isInteger(version) && version > 0;
+ return {
+ id: skill.name,
+ name: display_name ?? skill.name,
+ description: skill.description,
+ ...(repository_name === undefined ? {} : { skillRepoName: repository_name }),
+ ...(hasVersion
+ ? {
+ version,
+ loadVersions: async () => (await client.skills.listVersions({ name: skill.name })).data,
+ }
+ : {}),
+ };
+ });
},
getMcp: async () => (await listConfiguredMcpServers(client)).map(toUiConnectorFromReadEntry),
getMcpConnector: async ({ connectorId }: { connectorId: string }) => {
diff --git a/packages/trueforge-ui/test/atoms/draft/AgentConfigEditors.test.tsx b/packages/trueforge-ui/test/atoms/draft/AgentConfigEditors.test.tsx
index 1cbafaea6..ee25bc6c5 100644
--- a/packages/trueforge-ui/test/atoms/draft/AgentConfigEditors.test.tsx
+++ b/packages/trueforge-ui/test/atoms/draft/AgentConfigEditors.test.tsx
@@ -7,7 +7,7 @@ import { AgentConfigEditors } from '@/atoms/draft/AgentConfigEditors.js';
import { AgentModelSettingsContent } from '@/atoms/draft/AgentModelSettingsContent.js';
import { withInitialUserMessages } from '@/atoms/draft/agentConfigMessages.js';
import { ServerProvider } from '@/server/ServerContext.js';
-import type { AgentSpec, ConnectorState } from '@/server/types.js';
+import type { AgentSkill, AgentSpec, ConnectorState } from '@/server/types.js';
import { SlotsProvider } from '@/theme/SlotsProvider.js';
import { createMockAgentUIServer, createMockCatalog } from '../../server/mockServer.js';
@@ -1238,4 +1238,136 @@ describe('AgentConfigEditors', () => {
config: { sandbox: { enabled: true } },
});
});
+
+ it('reorders selected skills only when the skills editor reopens', () => {
+ const availableSkills = [
+ { id: 'alpha', name: 'Alpha' },
+ { id: 'beta', name: 'Beta' },
+ ];
+ const initialSpec: AgentSpec = { model: { name: 'openai/gpt' } };
+ const selectedSpec: AgentSpec = {
+ ...initialSpec,
+ skills: [{ id: 'beta', name: 'Beta' }],
+ };
+ const renderEditors = (spec: AgentSpec) => (
+ <SlotsProvider>
+ <AgentConfigEditors
+ editor="skills"
+ spec={spec}
+ models={[]}
+ connectors={[]}
+ skills={availableSkills}
+ loading={false}
+ error={null}
+ onChange={vi.fn()}
+ onClose={vi.fn()}
+ />
+ </SlotsProvider>
+ );
+ const rendered = render(renderEditors(initialSpec));
+
+ expect(screen.getAllByRole('menuitemcheckbox')[0]).toHaveTextContent('Alpha');
+ rendered.rerender(renderEditors(selectedSpec));
+ expect(screen.getAllByRole('menuitemcheckbox')[0]).toHaveTextContent('Alpha');
+
+ rendered.unmount();
+ render(renderEditors(selectedSpec));
+ expect(screen.getAllByRole('menuitemcheckbox')[0]).toHaveTextContent('Beta');
+ });
+
+ it('loads registry versions lazily and attaches the chosen FQN', async () => {
+ const spec: AgentSpec = { model: { name: 'openai/gpt' } };
+ const onChange = vi.fn();
+ const loadVersions = vi.fn(async () => [
+ {
+ name: 'agent-skill:acme/team-a/echo:1',
+ displayName: 'echo',
+ description: 'v1',
+ version: 1,
+ },
+ {
+ name: 'agent-skill:acme/team-a/echo:3',
+ displayName: 'echo',
+ description: 'v3',
+ version: 3,
+ },
+ ]);
+ const skill: AgentSkill = Object.assign(
+ {
+ id: 'agent-skill:acme/team-a/echo:3',
+ name: 'echo',
+ description: 'Echo skill',
+ },
+ { skillRepoName: 'team-a', version: 3, loadVersions },
+ );
+
+ render(
+ <SlotsProvider>
+ <AgentConfigEditors
+ editor="skills"
+ spec={spec}
+ models={[]}
+ connectors={[]}
+ skills={[skill]}
+ loading={false}
+ error={null}
+ onChange={onChange}
+ onClose={vi.fn()}
+ />
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByText('team-a')).toBeInTheDocument();
+ expect(loadVersions).not.toHaveBeenCalled();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Select version for echo' }));
+ fireEvent.click(await screen.findByRole('menuitem', { name: 'v1' }));
+ expect(loadVersions).toHaveBeenCalledOnce();
+ expect(onChange).not.toHaveBeenCalled();
+
+ fireEvent.click(screen.getByRole('checkbox', { name: 'Select echo' }));
+ expect(onChange).toHaveBeenCalledWith({
+ ...spec,
+ skills: [{ id: 'agent-skill:acme/team-a/echo:1', name: 'echo' }],
+ config: { sandbox: { enabled: true } },
+ });
+ });
+
+ it('shows a concise version error and copies its details', async () => {
+ const clipboardDescriptor = Object.getOwnPropertyDescriptor(navigator, 'clipboard');
+ const writeText = vi.fn().mockResolvedValue(undefined);
+ Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } });
+ const errorMessage =
+ 'HTTP Error: Not Found <Error><Message>BucketName contains sensitive details</Message></Error>';
+ const skill: AgentSkill = Object.assign(
+ { id: 'agent-skill:acme/team-a/echo:3', name: 'echo' },
+ { version: 3, loadVersions: vi.fn().mockRejectedValue(new Error(errorMessage)) },
+ );
+
+ render(
+ <SlotsProvider>
+ <AgentConfigEditors
+ editor="skills"
+ spec={{ model: { name: 'openai/gpt' } }}
+ models={[]}
+ connectors={[]}
+ skills={[skill]}
+ loading={false}
+ error={null}
+ onChange={vi.fn()}
+ onClose={vi.fn()}
+ />
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Select version for echo' }));
+ expect(await screen.findByText('Failed to load versions.')).toBeInTheDocument();
+ expect(screen.queryByText(errorMessage, { exact: false })).not.toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Copy error' }));
+ expect(writeText).toHaveBeenCalledWith(errorMessage);
+
+ if (clipboardDescriptor === undefined) Reflect.deleteProperty(navigator, 'clipboard');
+ else Object.defineProperty(navigator, 'clipboard', clipboardDescriptor);
+ });
});
diff --git a/packages/trueforge-ui/test/atoms/draft/AgentConfigPanel.test.tsx b/packages/trueforge-ui/test/atoms/draft/AgentConfigPanel.test.tsx
index a838211f8..f22e42e75 100644
--- a/packages/trueforge-ui/test/atoms/draft/AgentConfigPanel.test.tsx
+++ b/packages/trueforge-ui/test/atoms/draft/AgentConfigPanel.test.tsx
@@ -42,6 +42,7 @@ const catalogProps = {
models: [model, secondModel],
modelsLoading: false,
modelsError: null,
+ skills: [{ id: 'agent-skill:acme/team-a/echo:3', name: 'Echo', version: 3 }],
};
const spec: AgentSpec = {
@@ -302,6 +303,54 @@ describe('AgentConfigPanel', () => {
});
});
+ it('removes a skill directly from its config chip without offering preload for a git skill', () => {
+ const onChange = vi.fn();
+ render(
+ <SlotsProvider>
+ <AgentConfigPanel
+ spec={spec}
+ model={model}
+ {...catalogProps}
+ skillsAvailable
+ instructions={spec.instructions ?? ''}
+ onOpenEditor={vi.fn()}
+ onChange={onChange}
+ />
+ </SlotsProvider>,
+ );
+
+ expect(screen.queryByRole('button', { name: 'Preload skill Research' })).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Remove Research' }));
+ expect(onChange).toHaveBeenCalledWith({ ...spec, skills: [] });
+ });
+
+ it('toggles preload for an older version of a TrueFoundry skill', () => {
+ const onChange = vi.fn();
+ const registrySpec = {
+ ...spec,
+ skills: [{ id: 'agent-skill:acme/team-a/echo:2', name: 'Echo' }],
+ };
+ render(
+ <SlotsProvider>
+ <AgentConfigPanel
+ spec={registrySpec}
+ model={model}
+ {...catalogProps}
+ skillsAvailable
+ instructions={registrySpec.instructions ?? ''}
+ onOpenEditor={vi.fn()}
+ onChange={onChange}
+ />
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Preload skill Echo' }));
+ expect(onChange).toHaveBeenCalledWith({
+ ...registrySpec,
+ skills: [{ id: 'agent-skill:acme/team-a/echo:2', name: 'Echo', preload: true }],
+ });
+ });
+
it('leaves keyboard activation of chip controls to the chip', () => {
const onOpenEditor = vi.fn();
render(
diff --git a/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx b/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx
index 687b1790b..b8c990738 100644
--- a/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx
+++ b/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx
@@ -6,7 +6,7 @@ import { DraftCatalogProvider } from '@/atoms/draft/DraftCatalogProvider.js';
import { DraftCompositeSelector } from '@/atoms/draft/DraftCompositeSelector.js';
import { CompactLayoutProvider } from '@/atoms/lib/CompactLayoutContext.js';
import { ServerProvider } from '@/server/ServerContext.js';
-import type { AgentSpec, CatalogServer, SandboxCatalogServer, SkillCatalogServer } from '@/server/types.js';
+import type { AgentSkill, AgentSpec, CatalogServer, SandboxCatalogServer, SkillCatalogServer } from '@/server/types.js';
import { createMockAgentUIServer, createMockCatalog } from '../../server/mockServer.js';
let agentSpec: AgentSpec;
@@ -67,7 +67,7 @@ function renderSelector({
settings?: { enabled: boolean };
};
}>;
- getSkills?: () => Promise<{ id: string; name: string }[]>;
+ getSkills?: () => Promise<AgentSkill[]>;
getMcp?: () => Promise<{ id: string; name: string; authenticated: boolean }[]>;
catalog?: CatalogServer | null;
compact?: boolean;
@@ -140,6 +140,22 @@ describe('DraftCompositeSelector', () => {
expect(screen.queryByRole('dialog', { name: 'Add to composer' })).not.toBeInTheDocument();
});
+ it('keeps registry skills plain in the draft composer', async () => {
+ const loadVersions = vi.fn(async () => []);
+ const skill: AgentSkill = Object.assign(
+ { id: 'agent-skill:acme/team-a/echo:3', name: 'echo' },
+ { version: 3, loadVersions },
+ );
+ renderSelector({ getSkills: async () => [skill] });
+
+ fireEvent.click(screen.getByRole('button', { name: /Tools/ }));
+ fireEvent.click(screen.getByRole('button', { name: /Skills/ }));
+
+ expect(await screen.findByRole('menuitemcheckbox', { name: /echo/ })).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Select version for echo' })).not.toBeInTheDocument();
+ expect(loadVersions).not.toHaveBeenCalled();
+ });
+
it('uses contrasting search surfaces in light and dark themes', () => {
renderSelector();
fireEvent.click(screen.getByRole('button', { name: 'Tools (2)' }));
diff --git a/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx b/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx
index 8794ef0ff..27686a4ce 100644
--- a/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx
+++ b/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx
@@ -1,7 +1,7 @@
// @vitest-environment jsdom
import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import type { ReactNode } from 'react';
-import { beforeAll, describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
import SkillSettings from '@/containers/SettingsBuilder/SkillSettings.js';
import { ServerProvider } from '@/server/ServerContext.js';
@@ -183,4 +183,35 @@ describe('SkillSettings', () => {
]);
});
});
+
+ it('disables settings writes after TrueFoundry returns 424', async () => {
+ const createSkill = vi.fn(async () => {
+ throw Object.assign(new Error('Failed dependency'), {
+ statusCode: 424,
+ body: { error: { message: 'This resource is managed by TrueFoundry' } },
+ });
+ });
+ const server = createMockAgentUIServer({
+ catalog: createMockCatalog({
+ skillCatalog: {
+ getSkillCatalog: async () => [catalogEntry],
+ listSkills: async () => [],
+ createSkill,
+ },
+ }),
+ });
+
+ render(
+ <ServerProvider server={server}>
+ <SkillSettings />
+ </ServerProvider>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Enable Code Review' }));
+
+ expect(await screen.findByText('This resource is managed by TrueFoundry')).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Enable Code Review' })).toBeDisabled();
+ expect(screen.getByRole('button', { name: /Import from GitHub/ })).toBeDisabled();
+ expect(createSkill).toHaveBeenCalledOnce();
+ });
});
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 1b4a76ce2..86071c7bb 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
@@ -235,6 +235,62 @@ describe('harnessBuilderServer', () => {
});
});
+ it('maps registry skill metadata and loads versions on demand', async () => {
+ const urls: string[] = [];
+ const fetchMock: typeof fetch = async input => {
+ const url = input instanceof Request ? input.url : String(input);
+ urls.push(url);
+ if (url.endsWith('/api/v1/skills')) {
+ return Response.json({
+ data: [
+ {
+ name: 'agent-skill:acme/team-a/echo:3',
+ description: 'Echo skill',
+ metadata: {
+ display_name: 'echo',
+ repository_name: 'team-a',
+ version: '3',
+ },
+ },
+ ],
+ });
+ }
+ if (url.includes('/api/v1/skills/versions?')) {
+ return Response.json({
+ data: [
+ {
+ name: 'agent-skill:acme/team-a/echo:1',
+ display_name: 'echo',
+ description: 'v1',
+ version: 1,
+ },
+ ],
+ });
+ }
+ return new Response(`Unexpected request: ${url}`, { status: 500 });
+ };
+
+ const [skill] = await createHarnessBuilderServer({ fetch: fetchMock }).getSkills();
+ if (skill === undefined) throw new Error('expected skill');
+ assert.equal(skill.id, 'agent-skill:acme/team-a/echo:3');
+ assert.equal(skill.name, 'echo');
+ assert.equal(Reflect.get(skill, 'skillRepoName'), 'team-a');
+ assert.equal(Reflect.get(skill, 'version'), 3);
+ assert.equal(urls.length, 1);
+
+ const loadVersions = Reflect.get(skill, 'loadVersions');
+ if (typeof loadVersions !== 'function') throw new Error('expected version loader');
+ assert.deepEqual(await Reflect.apply(loadVersions, skill, []), [
+ {
+ name: 'agent-skill:acme/team-a/echo:1',
+ displayName: 'echo',
+ description: 'v1',
+ version: 1,
+ },
+ ]);
+ assert.equal(urls.length, 2);
+ });
+
it('searchAgents maps registry rows to library entries with agentId + agentSpec', async () => {
const fetchMock: typeof fetch = async input => {
const url = input instanceof Request ? input.url : String(input);